---
phase: 07-setup-wizard
plan: 01
subsystem: frontend/setup-wizard
tags: [wizard, ui, state-management, i18n]
dependency_graph:
  requires: [src/data/presets.ts, src/lib/types.ts, src/hooks/useAuth.ts]
  provides: [src/hooks/useWizardState.ts, src/pages/SetupPage.tsx, src/components/setup/*]
  affects: [src/i18n/en.json, src/i18n/de.json]
tech_stack:
  added: [shadcn/checkbox]
  patterns: [localStorage-synced-state, multi-step-wizard, grouped-preset-checklist]
key_files:
  created:
    - src/hooks/useWizardState.ts
    - src/components/setup/WizardStepper.tsx
    - src/components/setup/IncomeStep.tsx
    - src/components/setup/AllocationBar.tsx
    - src/components/setup/CategoryGroupHeader.tsx
    - src/components/setup/PresetItemRow.tsx
    - src/components/setup/RecurringItemsStep.tsx
    - src/pages/SetupPage.tsx
    - src/components/ui/checkbox.tsx
  modified:
    - src/i18n/en.json
    - src/i18n/de.json
decisions:
  - "Profile fetched inline in SetupPage (same pattern as SettingsPage) since useAuth does not expose profile"
  - "Used manual reduce for grouping PRESETS by type for broad browser compatibility"
metrics:
  duration: 178s
  completed: 2026-04-20T19:06:36Z
  tasks_completed: 2
  tasks_total: 2
  files_created: 9
  files_modified: 2
---

# Phase 07 Plan 01: Setup Wizard UI Shell Summary

LocalStorage-synced 3-step wizard with income input, grouped preset checklist (19 items), live allocation bar, and horizontal stepper navigation.

## Commits

| Task | Commit | Description |
|------|--------|-------------|
| 1 | bbcb07f | useWizardState hook, i18n keys (EN+DE), shadcn checkbox |
| 2 | e141197 | All 7 wizard UI components and SetupPage orchestrator |

## What Was Built

1. **useWizardState hook** - Manages wizard step, income, and item selections in localStorage keyed by userId. Validates JSON shape on load (T-07-01 mitigation). Bills and variable_expense items pre-checked by default.

2. **WizardStepper** - Horizontal 1-2-3 stepper with circles, connector lines, and step labels. Completed steps are clickable; future steps are disabled.

3. **IncomeStep** - Number input pre-filled with 3000, currency suffix from profile, helper text, and inline validation error display.

4. **AllocationBar** - Sticky bar showing remaining = income - sum(checked amounts). Green when positive, red (destructive) when negative. aria-live="polite" for screen readers.

5. **CategoryGroupHeader** - Colored dot + label + item count for each of the 6 category types.

6. **PresetItemRow** - Checkbox + preset name (i18n) + category badge with colored border + editable amount input (disabled when unchecked).

7. **RecurringItemsStep** - Groups all 19 PRESETS into 6 category sections with AllocationBar at top.

8. **SetupPage** - Page orchestrator: centered card layout (max-w-2xl), loads profile for currency, renders stepper + active step, handles Next/Back/Skip navigation with income validation.

## i18n

All wizard copy added under `setup.*` namespace in both `en.json` and `de.json` (35 keys each). German translations use proper umlauts and natural phrasing.

## Deviations from Plan

None - plan executed exactly as written.

## Known Stubs

| File | Line | Stub | Reason |
|------|------|------|--------|
| src/pages/SetupPage.tsx | Step 3 content | "Review step coming in next plan" placeholder | Plan 02 will implement ReviewStep and completion logic |
| src/pages/SetupPage.tsx | Skip setup button | No-op onClick | Plan 02 will wire skip to mark setup_completed and redirect |
| src/pages/SetupPage.tsx | Complete button | Disabled, no handler | Plan 02 will implement completion sequence |

These stubs are intentional -- Plan 02 explicitly owns the ReviewStep, completion logic, routing, and redirect.

## Self-Check: PASSED