SimpleFinanceDash/.planning/ROADMAP.md

Roadmap: SimpleFinanceDash v2.0 — UX Simplification & Design Rework

Overview

This milestone transforms SimpleFinanceDash from a visually polished but cognitively complex app into a guided, intuitive budgeting experience. Work flows from a global design token rework (sharp edges, clearer pastels) through data safety foundations, a wizard-driven first-run setup, automatic budget creation, and finally a simplified budget view with inline item adding. Every phase delivers a coherent, verifiable capability on top of the fully working v1.0 baseline.

Phases

Phase Numbering:

• Integer phases (5-9): v2.0 milestone work, continuing from v1.0's Phase 4
• Decimal phases: Urgent insertions if needed (marked INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 5: Design System Token Rework - Replace rounded corners with sharp edges and refine OKLCH pastel tokens across all 9 pages
• Phase 6: Preset Data, First-Run Detection, and DB Safety - Seed preset library, build first-run hook, and add DB uniqueness constraints that protect against duplicate data
• Phase 7: Setup Wizard - 3-step first-run wizard with income, pre-filled recurring items, and review — skippable, state-persisted, bilingual
• Phase 8: Auto-Budget Creation - Auto-create current month's budget from template on dashboard visit, with correct currency and first-creation toast
• Phase 9: Inline Add and Dashboard Simplification - Replace Quick Add page with inline Sheet panel, simplify dashboard to at-a-glance view, add empty states

Phase Details

Phase 5: Design System Token Rework

Goal: Users see a sharp, minimal, clearly pastel UI across every page — the visual foundation that all subsequent phases build on Depends on: Phase 4 (v1.0 complete) Requirements: DS-01, DS-02, DS-03 Success Criteria (what must be TRUE):

1. Every rounded element across all 9 pages has sharp corners — no pill buttons, no rounded cards, no rounded inputs visible anywhere in the app
2. Category color swatches are visibly colorful against white backgrounds — not washed-out or grey-tinted — and still pass WCAG 4.5:1 contrast for text
3. Page layouts feel uncluttered — content sections have consistent whitespace gaps and no visual crowding between cards or sections
4. A full visual pass of all 9 pages (Dashboard, Budget List, Budget Detail, Template, Categories, Quick Add, Settings, Login, Register) confirms no regressions from token changes Plans: 3 plans Plans:

• 05-01-PLAN.md — Design tokens (radius, colors, chart vars) and chart component Bar radius updates
• 05-02-PLAN.md — Shared component rounded-* removal and spacing upgrades (PageShell, DashboardSkeleton, CategorySection, ChartEmptyState, QuickAddPicker)
• 05-03-PLAN.md — Per-page sweep (all 9 pages) for rounded-* removal, spacing upgrades, and visual verification checkpoint

Phase 6: Preset Data, First-Run Detection, and DB Safety

Goal: The data layer is safe and ready — duplicate budget/category writes are impossible at the DB level, and the app correctly identifies first-run users Depends on: Phase 5 Requirements: AUTO-01, AUTO-03, SETUP-01, SETUP-02 Success Criteria (what must be TRUE):

1. Attempting to create two budgets for the same user and month is rejected at the DB level (unique constraint on budgets(user_id, start_date))
2. Attempting to create two categories with the same name for the same user is rejected at the DB level (unique constraint on categories(user_id, name))
3. All existing v1.0 users have profiles.setup_completed = true after the backfill migration runs — they will not be shown the wizard on their next login
4. useFirstRunState hook returns true only for users with zero categories or zero template items — returning false for any user with existing data
5. src/data/presets.ts contains ~15-20 curated budget items with sensible default amounts, grouped by category type, with both English and German i18n translation keys defined Plans: TBD

Phase 7: Setup Wizard

Goal: 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 Depends on: Phase 6 Requirements: SETUP-01, SETUP-02, SETUP-03, SETUP-04, SETUP-05 Success Criteria (what must be TRUE):

1. A new user (zero categories, zero template items) is automatically redirected to /setup on their first login and sees a 3-step wizard: income entry, recurring items selection, and review
2. The recurring items step shows ~15-20 pre-filled common items (rent, groceries, car insurance, utilities, etc.) with editable default amounts — user can check or uncheck each
3. A "remaining to allocate" balance updates live as items are checked or unchecked in step 2, showing income minus the sum of selected item amounts
4. User can click "Skip" on any individual step or "Skip setup" to exit the wizard entirely without creating any data — and lands on the dashboard
5. Completing the wizard creates a populated template from selected items — user lands on the dashboard with their template in place, and refreshing the browser mid-wizard restores the wizard at the correct step Plans: TBD

Phase 8: Auto-Budget Creation

Goal: Users never manually trigger budget creation — visiting a month for the first time automatically creates their budget from the template, silently and correctly Depends on: Phase 7 Requirements: AUTO-01, AUTO-02, AUTO-03 Success Criteria (what must be TRUE):

1. Navigating to the dashboard for a month that has no budget (but a populated template) creates the budget automatically — no button click or prompt required
2. The first time a budget is auto-created in a session, a toast notification appears naming the month and indicating it was created from the template — subsequent months are created silently
3. The auto-created budget uses the user's configured currency from their profile settings, not a hardcoded default
4. Rapidly navigating between months or opening the dashboard in two tabs does not produce duplicate budget rows Plans: TBD

Phase 9: Inline Add and Dashboard Simplification

Goal: Users add one-off items to their budget directly from the budget view, the Quick Add page is gone, and the dashboard shows this month's data at a glance without chart overload Depends on: Phase 8 Requirements: BV-01, BV-02, BV-03, DASH-01, DASH-02, DASH-03 Success Criteria (what must be TRUE):

1. An "Add item" control on the budget detail page opens a Sheet panel showing the category library — user selects a category, enters an amount, and the item appears in the budget without a page navigation
2. The Quick Add page is removed from the sidebar navigation — visiting /quick-add redirects to /budgets instead of showing an error
3. The dashboard displays this month's summary cards (income, expenses, balance) with correct totals that match what the user entered in the budget detail page
4. The dashboard does not show the 3-column chart grid by default — the primary view is the at-a-glance summary and collapsible category sections
5. Empty template, empty dashboard, and empty budget view each show a clear empty state with a visible call-to-action guiding the user to the next step Plans: TBD

Requirements Traceability

Requirement	Phase	Status
DS-01	Phase 5	Pending
DS-02	Phase 5	Pending
DS-03	Phase 5	Pending
SETUP-01	Phase 6, 7	Pending
SETUP-02	Phase 6, 7	Pending
SETUP-03	Phase 7	Pending
SETUP-04	Phase 7	Pending
SETUP-05	Phase 7	Pending
AUTO-01	Phase 6, 8	Pending
AUTO-02	Phase 8	Pending
AUTO-03	Phase 6, 8	Pending
BV-01	Phase 9	Pending
BV-02	Phase 9	Pending
BV-03	Phase 9	Pending
DASH-01	Phase 9	Pending
DASH-02	Phase 9	Pending
DASH-03	Phase 9	Pending

Coverage: 17/17 v2.0 requirements mapped. No orphans.

Progress

Execution Order: Phases execute in numeric order: 5 → 6 → 7 → 8 → 9

Phase	Plans Complete	Status	Completed
5. Design System Token Rework	0/3	Planned	-
6. Preset Data, First-Run Detection, DB Safety	0/?	Not started	-
7. Setup Wizard	0/?	Not started	-
8. Auto-Budget Creation	0/?	Not started	-
9. Inline Add and Dashboard Simplification	0/?	Not started	-