136 lines
9.7 KiB
Markdown
136 lines
9.7 KiB
Markdown
# 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
|
|
- [x] **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
|
|
- [x] **Phase 7: Setup Wizard** - 3-step first-run wizard with income, pre-filled recurring items, and review — skippable, state-persisted, bilingual (completed 2026-04-20)
|
|
- [ ] **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:
|
|
- [x] 05-01-PLAN.md — Design tokens (radius, colors, chart vars) and chart component Bar radius updates
|
|
- [x] 05-02-PLAN.md — Shared component rounded-* removal and spacing upgrades (PageShell, DashboardSkeleton, CategorySection, ChartEmptyState, QuickAddPicker)
|
|
- [x] 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:** 3 plans
|
|
Plans:
|
|
- [x] 06-01-PLAN.md — DB migrations (uniqueness constraints + setup_completed column + Profile type update)
|
|
- [x] 06-02-PLAN.md — Preset library (src/data/presets.ts) and i18n translations (en.json + de.json)
|
|
- [x] 06-03-PLAN.md — useFirstRunState hook, DB schema push, and verification checkpoint
|
|
|
|
### 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:** 2/2 plans complete
|
|
Plans:
|
|
- [x] 07-01-PLAN.md — Wizard state hook, i18n keys, stepper + step 1/2 UI components (income, recurring items, allocation bar)
|
|
- [x] 07-02-PLAN.md — ReviewStep, completion logic, skip handling, /setup route, first-run redirect, and verification checkpoint
|
|
|
|
### 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:** 3 plans
|
|
Plans:
|
|
- [ ] 06-01-PLAN.md — DB migrations (uniqueness constraints + setup_completed column + Profile type update)
|
|
- [ ] 06-02-PLAN.md — Preset library (src/data/presets.ts) and i18n translations (en.json + de.json)
|
|
- [ ] 06-03-PLAN.md — useFirstRunState hook, DB schema push, and verification checkpoint
|
|
|
|
### 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:** 3 plans
|
|
Plans:
|
|
- [ ] 06-01-PLAN.md — DB migrations (uniqueness constraints + setup_completed column + Profile type update)
|
|
- [ ] 06-02-PLAN.md — Preset library (src/data/presets.ts) and i18n translations (en.json + de.json)
|
|
- [ ] 06-03-PLAN.md — useFirstRunState hook, DB schema push, and verification checkpoint
|
|
|
|
## 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 | 3/3 | Complete | 2026-04-20 |
|
|
| 7. Setup Wizard | 2/2 | Complete | 2026-04-20 |
|
|
| 8. Auto-Budget Creation | 0/? | Not started | - |
|
|
| 9. Inline Add and Dashboard Simplification | 0/? | Not started | - |
|