Phase 7: Setup Wizard - Context

Gathered: 2026-04-20 Status: Ready for planning

## Phase Boundary

A new user can set up their budget template in under 3 minutes by following a guided 3-step wizard with pre-filled common items and a live running balance. The wizard auto-redirects first-run users (detected by useFirstRunState), creates categories and template items on completion, persists state across refreshes, and supports skip at any point. Bilingual (EN/DE) via existing i18n system.

## Implementation Decisions

Numbered horizontal stepper (1-2-3 bar at top) — minimal, clear progress indicator
Centered card layout (max-w-2xl) on clean background — consistent with auth pages
Next/Back buttons at bottom + step indicator is clickable for going back
Same centered card on mobile, full-width breakpoint — project is desktop-first

Income Step (Step 1)

Single "monthly net income" number input — simplest mental model
Pre-filled with 3000 (PRESETS salary default), user can clear and type their own
Show user's profile currency (EUR) from useAuth/profile next to input
Required field, must be > 0, numeric only — can't proceed without income entered

Recurring Items Step (Step 2)

Full checklist: all 19 PRESETS shown, grouped by category type, with item name + category badge + editable amount per row
Bills (4) + variable_expense (5) pre-checked by default — focuses on spending categories the wizard is about
Income/debt/saving/investment items unchecked by default
Sticky bar at top: "Remaining to allocate: Income - sum(checked) = X" — turns red when negative
Inline number input per item, only editable when item is checked

Review Step & Completion (Step 3)

Read-only summary card: income at top, grouped checked items with amounts below, total and remaining at bottom
"Complete" creates categories (from checked item types that don't already exist) + template items (from checked items with amounts)
Does NOT create first month's budget (Phase 8 handles auto-budget creation)
After completion: redirect to / (dashboard) with success toast "Template created! Your first budget will appear automatically."

Skip & State Persistence

"Skip" button on each step + global "Skip setup" to exit wizard entirely without creating data
Wizard state persisted in localStorage keyed by user_id — survives page refresh
On complete or skip: clear localStorage, mark profiles.setup_completed = true
Refreshing mid-wizard restores the wizard at the correct step

Claude's Discretion

Exact component decomposition (how many sub-components for the wizard)
Animation/transition between steps (if any)
Exact styling of category badges and grouping headers
Toast message wording variations
Error handling UX for failed API calls during completion

<code_context>

Existing Code Insights

Reusable Assets

src/hooks/useFirstRunState.ts — detects first-run users (isFirstRun + loading)
src/hooks/useCategories.ts — CRUD for categories (create method available)
src/hooks/useTemplate.ts — CRUD for template items (createItem method available)
src/hooks/useAuth.ts — profile access (currency, locale)
src/data/presets.ts — 19 PresetItem entries with slug, type, defaultAmount, item_tier
src/components/ui/card.tsx — Card component
src/components/ui/button.tsx — Button component
src/components/ui/input.tsx — Input component
src/components/ui/badge.tsx — Badge component (for category type indicators)
src/components/ui/sonner.tsx — Toast notifications
src/i18n/en.json + de.json — presets.* keys already translated

Established Patterns

Pages are in src/pages/*.tsx, routed via React Router
Hooks use React Query with Supabase client
Category types: income, bill, variable_expense, debt, saving, investment
UI uses Tailwind + shadcn/ui components with OKLCH pastel design tokens
Auth-protected routes via layout wrapper

Integration Points

Router: Add /setup route, redirect logic in dashboard or layout
useFirstRunState() — gate for redirect (check !loading && isFirstRun)
useCategories().create — create categories on wizard completion
useTemplate().createItem — create template items on wizard completion
profiles.setup_completed — mark true on completion/skip via Supabase update

</code_context>

## Specific Ideas

Pre-filled common items come from the existing PRESETS array (19 items, already i18n'd)
The "remaining to allocate" balance = income entered in step 1 minus sum of checked item amounts in step 2
Wizard must not create duplicate categories if user already has some (edge case: user skipped wizard, manually created categories, then somehow re-enters wizard)
Phase 6 decisions: round EUR amounts, backfill existing users to setup_completed=true (they never see wizard)

## Deferred Ideas

None — discussion stayed within phase scope.

5.0 KiB Raw Blame History