Skip to main content

Rewhaven Auth + Onboarding — Branded First Impression (design spec, 2026-06-20)

Brainstormed + approved 2026-06-20. The entry experience (intro → welcome → auth forms → setup) is the first impression of the app; today it is bare forms. This spec makes it carry the marketing site's calm dusk brand while staying usable, accessible, and reduced-motion-respecting — "lush but calm."

Revisit post-alpha if it needs changing (user's call). This spec is one focused unit of work → its own implementation plan.

Goal​

Turn the auth/onboarding from plain forms into a branded, atmospheric first impression that matches rewhaven.com — without compromising legibility, a11y, or the calm/low-stim thesis the rest of the app honors.

Brand anchors (carried from the marketsite)​

  • Voice (verbatim from rewhaven-marketsite src/brand.ts): 🌙 · tagline "The evening routine, without the evening battle." · "a calm, neurodiversity-affirming way for your family to share the work of home — built on trust, not punishment, and designed to make itself unnecessary." The "doors" beats: a different bet (scaffold not scoreboard) · for your family · free forever.
  • Visual: a dusk sky — soft aurora glows (warm + cool), a few slowly drifting/twinkling stars, the rooftop skyline with gently glowing windows; Bricolage Grotesque display + Atkinson Hyperlegible body; a warm glow-amber emphasis word in headlines.
  • Already in the design system (ported earlier): DsRooftops, DsConstellation, DsVignette (rooftops / constellation / coins scenes), and the glow / auroraWarm / auroraCool / star / roof tokens. This spec composes those; it does not invent new brand art.

The flow​

  • First-time: Splash (🌙) → Intro carousel (3 screens) → Welcome → Create account → Setup wizard → Today.
  • Returning: Splash → straight to Today if a session exists; else Welcome → Sign in → Today.
  • A seenIntro flag (SharedPrefs, via the existing prefs effect) shows the carousel only once. A needsSetup signal (no household yet) routes a fresh account into the wizard before Today.

Screens​

1. Intro carousel — full-dusk "A" treatment​

Swipeable PageView, Skip top-right, page dots, the three brand beats; each beat is a DsVignette scene + a Bricolage headline with a glow-emphasis word

  • one calm line:
  1. The promise — rooftops vignette · "The evening routine, without the evening battle." · "A calm way for your family to share the work of home."
  2. The bet — constellation vignette · "A scaffold, not a scoreboard." · "Built on trust, not punishment — expectations that don't shame, bounties they choose."
  3. The trust — coins vignette · "Yours, and private." · "Free at the core, forever · Works offline · Photos never leave the phone." → [Get started].

2. Welcome — full-dusk "A" treatment (the hub)​

🌙 + the rewhaven wordmark + a warm line ("Welcome home"), composed over the rooftop skyline (glowing windows) with a soft aurora + a few drifting stars. CTAs: [Create your household] (primary teal) + "Already have an account? Sign in." This is where the marketsite's "doors / coming home at dusk" feeling lives.

3. Auth forms — clean-panel "B" treatment​

A shared AuthScaffold = a dusk AuthHeroBand on top (aurora + a few stars + the rooftop silhouette + a Bricolage headline with the glow word) over a clean solid form panel below. Inputs always sit on the solid surface, so AA contrast is guaranteed; the atmosphere lives only in the band.

  • Sign in — band "Welcome home"; DsEmailField + DsPasswordField + Sign in + "Forgot password?" + "Create your household".
  • Sign up — band "Create your household"; DsUsernameField + DsEmailField + DsPasswordField + confirm-password + Create account + "Sign in".
  • Forgot password — band "Reset your password"; DsEmailField + Send reset link → the calm "Check your email" confirmation (no account enumeration).

The forms already built (sign-in/sign-up/forgot) barely change — they are wrapped in AuthScaffold and gain the band; the field molecules and blocs stay.

4. Setup wizard — atmosphere dials DOWN into the calm app​

A WizardScaffold (progress bar + step body + CTA), 3 steps, behind a small SetupBloc. The atmosphere fades step by step (a hint of aurora at top → the calm app surface) so the user is gently handed off from the branded entrance into the quiet daily app.

  1. Name your home — household-name field + emoji picker → createHousehold (or setHouseholdName if one exists).
  2. Add your first kid — name + kid colour (kidColor) + emoji → addMember(kind: child). "Skip for now" allowed.
  3. You're home — a soft celebratory finish (🌙 + "You're home" + " is ready") → [Go to Today].

Components​

New (app-level unless noted):

  • AuthHeroBand — the reusable dusk backdrop (rooftop + aurora + stars + headline-with-glow). May live in design_system if it's brand-generic, or in the app if it carries auth copy; decide during the plan.
  • AuthScaffold — hero band + clean form slot; wraps the existing forms.
  • OnboardingCarousel + the 3 intro screens.
  • WelcomeScreen.
  • WizardScaffold + the 3 setup steps.
  • SetupBloc — @JsonSerializable + Equatable + Status enum + toJson/fromJson (the DevTools serialization contract), wiring createHousehold/addMember.
  • The seenIntro SharedPrefs flag + the needsSetup routing gate.

Reused: DsRooftops, DsConstellation, DsVignette, the identity molecules (DsEmailField/DsUsernameField/DsPasswordField), DsButton, DsTextField, DsSection, the existing sign-in/sign-up/forgot forms + their blocs, the SdkClientProvider + repositories, the SharedPrefs effect, the nav/bloc observers (page + funnel analytics).

Routing: new anon/ routes (intro, welcome) + the post-auth setup route, the existing UnauthenticatedGuard/AuthenticatedGuard, plus the seenIntro and needsSetup gates. auto_route codegen.

Motion​

All from the brand, all slow + gentle ("quiet celebration"): aurora drift, occasional star twinkle, soft rooftop-window glow, and a content "reveal" rise-in per screen. Carousel = soft swipe; wizard = soft step transition. Every animation is static under reduced-motion via the existing MotionTokens.durationOrZero / MediaQuery.disableAnimationsOf path — one code path, no separate branch.

Accessibility / contrast​

  • Forms keep inputs on the solid panel → AA contrast guaranteed; the atmosphere is confined to the hero band.
  • Full-dusk screens (intro/welcome): the large Bricolage headlines + the warm glow emphasis word clear AA on the night background; the vignettes are decorative (ExcludeSemantics / aria-hidden).
  • Reduced-motion → static everywhere.
  • Semantics(identifier: ...) on the key controls (Get started, Create your household, Sign in, the wizard CTAs) so Maestro resolves them (Maestro's Flutter driver matches semantics identifiers, not Keys — established convention).
  • Proper heading/label semantics; keyboard focus rings (a11y floor, decision 5).

Testing​

  • Gadfly flow tests for each new flow, across the light/dark/focus trips: intro carousel (Skip → Welcome; Get started → Welcome), Welcome → Sign up / Sign in, and the 3-step Setup wizard → Today. expectedEvents transcripts incl. the page/analytics lines. Goldens (fonts + monochrome emoji already wired).
  • Unit: SetupBloc state transitions (name → add kid → done; skip path; error path) over the in-memory client / mocked repositories.
  • Maestro: an onboarding e2e flow on the seeded demo (intro → welcome → create account → wizard → Today). Authored; runnable on the emulator/device.
  • Atmosphere widgets: static (reduced-motion) goldens for AuthHeroBand and the intro/welcome compositions.

Scope / sequencing (for the implementation plan)​

Build in shippable phases, each tested:

  1. AuthHeroBand + AuthScaffold, restyle the 3 existing forms — the smallest change for the biggest immediate brand lift; the forms already exist.
  2. WelcomeScreen + routing (welcome as the unauthenticated hub).
  3. OnboardingCarousel + the seenIntro flag (the 3 intro beats).
  4. SetupWizard + SetupBloc + post-signup needsSetup routing.

Out of scope / deferred​

  • Post-alpha redesign tweaks (explicitly revisitable per the user).
  • The marketsite-Storybook parity (separate cross-repo effort).
  • Bundling Noto Color Emoji at runtime (decision 6, separate).
  • No layout A/B — the hybrid (full-dusk "A" for intro/welcome, hero-band "B" for forms) is the chosen direction.