User Onboarding Flow
Build a multi-step onboarding that captures real user data, persists progress, and lands users in a personalized app.
The route
6 steps to Done
- 01
Define onboarding steps and data
Decide exactly what to ask, why, and where each answer lives.
Preview prompt + verify gate ▾ Hide ▴
Define the onboarding spec. List 3-5 steps, each with: the single question/decision, the input type, validation rules, whether it is required, and the exact profile field it writes to. Add an onboardingCompleted flag and onboardingStep pointer to the user model. State how each answer will personalize the app (at least one concrete use per answer).
- ✓ Each step maps to a profile field
- ✓ Required vs optional is marked
- ✓ Each answer has a stated use in the app
- 02
Build the wizard shell
A solid multi-step frame: progress, navigation, and validation gates.
Preview prompt + verify gate ▾ Hide ▴
Build the onboarding wizard UI. Requirements: a step indicator (e.g. 2 of 4) with progress bar; Next/Back navigation; Next disabled until the current step validates, with inline errors; smooth step transitions; a final review/finish step; mobile responsive. Route new users here after signup. Keep answers in wizard state for now.
- ✓ Progress indicator matches the current step
- ✓ Next is blocked by validation with visible errors
- ✓ Back preserves earlier answers
- 03
Persist answers per step
Save as you go so progress and answers survive anything.
Preview prompt + verify gate ▾ Hide ▴
Implement persistence. Requirements: each completed step saves its answer and the onboardingStep pointer to the user record via the backend; refreshing mid-wizard resumes at the saved step with earlier answers pre-filled; finishing sets onboardingCompleted=true; all saves show subtle progress/error feedback. Verify by refreshing at step 3 and checking the database record.
- ✓ Refresh at any step resumes correctly
- ✓ Answers appear in the database as you progress
- ✓ Finish sets the completed flag
- 04
Add routing rules
Onboarding must gate correctly: incomplete users in, completed users out.
Preview prompt + verify gate ▾ Hide ▴
Implement onboarding routing. Requirements: users with onboardingCompleted=false are redirected into the wizard from any app page; completed users opening /onboarding are sent to the dashboard; logged-out users cannot access onboarding; there is no path to the app that skips required steps. Test all four cases explicitly.
- ✓ Incomplete user is pulled back into the wizard from the dashboard
- ✓ Completed user cannot re-enter the wizard accidentally
- ✓ No skip path bypasses required steps
- 05
Personalize the app from answers
Prove the data matters: the app must visibly use what it asked for.
Preview prompt + verify gate ▾ Hide ▴
Wire personalization. Requirements: at least two app surfaces reflect onboarding answers (e.g. greeting uses their name, dashboard shows content for their selected use-case/preference); answers are editable later in settings and edits propagate; show before/after evidence that changing an answer changes the surface.
- ✓ Two surfaces change based on answers
- ✓ Editing the answer in settings updates the surface
- 06
Onboarding QA pass
Verify the wizard, persistence, routing, and personalization end to end.
Preview prompt + verify gate ▾ Hide ▴
Run onboarding QA and report PASS/FAIL with evidence: fresh signup routes into the wizard; validation blocks bad input; refresh at step 3 resumes; finish lands on a personalized dashboard; re-login skips the wizard; settings edit propagates; mobile pass at 375px. Fix all failures and re-run.
- ✓ Fresh-account run executed end to end
- ✓ Resume and skip rules verified
- ✓ Personalization evidence captured
- ✓ All failures fixed