SimpleFinanceDash/.planning/ROADMAP.md

# Roadmap: SimpleFinanceDash UI/UX Overhaul

## Overview

This milestone transforms SimpleFinanceDash from a functional-but-basic budget app into a visually rich, cohesive personal finance dashboard. The overhaul is strictly UI-only — no backend or schema changes. Work flows from design foundations (tokens, shared components) through the dashboard (charts, collapsible sections) to full-app consistency across all 9 pages. The research phase is complete; all four phases use well-documented patterns and require no further research before planning.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [x] **Phase 1: Design Foundation and Primitives** - Install shadcn primitives, extend color tokens, build PageShell and StatCard/SummaryStrip
- [x] **Phase 2: Dashboard Charts and Layout** - Build DashboardContent orchestrator with all three chart types and month navigation (completed 2026-03-16)
- [ ] **Phase 3: Collapsible Dashboard Sections** - Add CategorySection with Radix Collapsible, BudgetLineItems, and group totals
- [ ] **Phase 4: Full-App Design Consistency** - Apply PageShell and established patterns to all 9 non-dashboard pages

## Phase Details

### Phase 1: Design Foundation and Primitives
**Goal**: Establish the design system building blocks — color tokens, shadcn primitives, and shared components — so all subsequent phases build on a consistent visual foundation
**Depends on**: Nothing (first phase)
**Requirements**: UI-DASH-01, UI-DESIGN-01, UI-RESPONSIVE-01
**Research flag**: No — Tailwind v4 `@theme inline`, OKLCH tokens, and WCAG contrast requirements are well-documented
**Success Criteria** (what must be TRUE):
  1. Running `npx shadcn@latest add chart` and `npx shadcn@latest add collapsible` has installed both primitives, and `chart.tsx` has the `initialDimension` patch applied (no `width(-1)` console warnings when rendering a test chart)
  2. `index.css` `@theme inline` block contains extended category color tokens with richer chroma and semantic status tokens (`--color-over-budget`, `--color-on-budget`), and all semantic color pairs pass WCAG 4.5:1 contrast for text
  3. `PageShell` component renders a consistent page header with title, optional description, and CTA slot — and is importable from `components/shared/`
  4. `StatCard` and `SummaryStrip` components render KPI cards (income, expenses, balance) with semantic color coding and variance badges — visible on the dashboard page
  5. Skeleton loading components exist that mirror the real card and chart layout structure
**Plans**: 2 plans

Plans:
- [x] 01-01-PLAN.md — Install shadcn primitives (chart + collapsible), extend OKLCH color tokens, add i18n keys
- [x] 01-02-PLAN.md — Build PageShell, StatCard, SummaryStrip, DashboardSkeleton and integrate into DashboardPage

### Phase 2: Dashboard Charts and Layout
**Goal**: Deliver the full dashboard chart suite — donut, vertical bar, and horizontal bar — inside a responsive 3-column layout, with month navigation and memoized data derivations
**Depends on**: Phase 1
**Requirements**: UI-DASH-01, UI-BAR-01, UI-HBAR-01, UI-DONUT-01
**Research flag**: No — Recharts 2.15.4 chart implementations and the `chart.tsx` fix are fully documented
**Success Criteria** (what must be TRUE):
  1. Dashboard displays an expense donut chart with center total label, active sector hover expansion, and a custom legend — replacing the existing flat pie chart
  2. Dashboard displays a grouped vertical bar chart comparing income budgeted vs actual amounts
  3. Dashboard displays a horizontal bar chart comparing budget vs actual spending by category type
  4. All three charts consume colors from CSS variable tokens (no hardcoded hex values) and render correctly with zero-item budgets (empty state)
  5. User can navigate between budget months on the dashboard without leaving the page, and all charts and cards update to reflect the selected month
**Plans**: 3 plans

Plans:
- [ ] 02-01-PLAN.md — Month navigation infrastructure (useMonthParam hook, MonthNavigator, ChartEmptyState, i18n keys)
- [ ] 02-02-PLAN.md — Three chart components (ExpenseDonutChart, IncomeBarChart, SpendBarChart)
- [ ] 02-03-PLAN.md — Dashboard integration (wire charts + month nav into DashboardPage, update skeleton)

### Phase 3: Collapsible Dashboard Sections
**Goal**: Complete the dashboard hybrid view with collapsible per-category sections that show individual line items, group totals, and variance indicators
**Depends on**: Phase 2
**Requirements**: UI-DASH-01, UI-COLLAPSE-01
**Research flag**: No — Radix Collapsible API and animation pattern are well-documented
**Success Criteria** (what must be TRUE):
  1. Each category group (income, bills, variable expenses, debt, savings, investment) renders as a collapsible section with a color-accented header showing the group label, budgeted total, actual total, and difference
  2. Expanding a section reveals a line-item table with individual budget items, and collapsing it hides the table with a smooth CSS animation (no layout shift in charts above)
  3. Toggling sections rapidly does not produce `ResizeObserver loop` console errors or visible chart resize jank
  4. Carryover amount is visible on the dashboard balance card when the budget has a non-zero carryover
**Plans**: 2 plans

Plans:
- [ ] 03-01-PLAN.md — Build carryover display, CSS animation tokens, i18n keys, CategorySection and CollapsibleSections components
- [ ] 03-02-PLAN.md — Wire collapsible sections into DashboardContent with smart defaults, update skeleton, verify

### Phase 4: Full-App Design Consistency
**Goal**: Apply the design system established in Phases 1-3 to every page in the app, delivering a consistent visual experience across all navigation paths
**Depends on**: Phase 3
**Requirements**: UI-DESIGN-01, UI-AUTH-01, UI-CATEGORIES-01, UI-TEMPLATE-01, UI-BUDGETS-01, UI-QUICKADD-01, UI-SETTINGS-01, UI-RESPONSIVE-01
**Research flag**: No — PageShell application and page-by-page refresh are repetitive pattern application
**Success Criteria** (what must be TRUE):
  1. All 9 pages (Login, Register, Categories, Template, Budget List, Budget Detail, Quick Add, Settings, Dashboard) use `PageShell` for their header and share the same typography, card style, and color token usage
  2. Login and Register pages have a refreshed visual design with the same card and color patterns as the dashboard
  3. Budget Detail page displays category groups with the same color-accented card style and line-item presentation as the dashboard collapsible sections
  4. Navigating between any two pages in the app produces no jarring visual discontinuity in layout, color, or typography
  5. Switching the app to German locale shows fully translated text on every page — no raw i18n key strings visible anywhere
**Plans**: TBD

Plans:
- [ ] 04-01: TBD
- [ ] 04-02: TBD

## Requirements Traceability

### Requirement Definitions

| ID | Requirement | Source |
|-----|-------------|--------|
| UI-DASH-01 | Redesign dashboard with hybrid layout — summary cards, charts, and collapsible category sections with budget/actual columns | PROJECT.md Active |
| UI-BAR-01 | Add bar chart comparing income budget vs actual | PROJECT.md Active |
| UI-HBAR-01 | Add horizontal bar chart comparing spend budget vs actual by category type | PROJECT.md Active |
| UI-DONUT-01 | Improve donut chart for expense category breakdown with richer styling | PROJECT.md Active |
| UI-COLLAPSE-01 | Add collapsible inline sections on dashboard for each category group showing individual line items | PROJECT.md Active |
| UI-DESIGN-01 | Redesign all pages with rich, colorful visual style — consistent design language across the app | PROJECT.md Active |
| UI-AUTH-01 | Refresh login and register pages | PROJECT.md Active |
| UI-CATEGORIES-01 | Refresh categories page | PROJECT.md Active |
| UI-TEMPLATE-01 | Refresh template page | PROJECT.md Active |
| UI-BUDGETS-01 | Refresh budget list and budget detail pages | PROJECT.md Active |
| UI-QUICKADD-01 | Refresh quick-add page | PROJECT.md Active |
| UI-SETTINGS-01 | Refresh settings page | PROJECT.md Active |
| UI-RESPONSIVE-01 | Desktop-first responsive layout across all pages | PROJECT.md Active |

### Coverage Map

| Requirement | Phase | Rationale |
|-------------|-------|-----------|
| UI-DASH-01 | Phase 1, 2, 3 | Dashboard hybrid layout spans foundation (cards), charts, and collapsible sections — each phase delivers one layer |
| UI-BAR-01 | Phase 2 | Income bar chart is a chart component built in the charts phase |
| UI-HBAR-01 | Phase 2 | Horizontal spend bar chart is a chart component built in the charts phase |
| UI-DONUT-01 | Phase 2 | Donut chart restyle is a chart component built in the charts phase |
| UI-COLLAPSE-01 | Phase 3 | Collapsible sections are the sole focus of Phase 3 |
| UI-DESIGN-01 | Phase 1, 4 | Design tokens and shared components in Phase 1; applied to all pages in Phase 4 |
| UI-AUTH-01 | Phase 4 | Login/register refresh uses established design patterns |
| UI-CATEGORIES-01 | Phase 4 | Categories page refresh uses established design patterns |
| UI-TEMPLATE-01 | Phase 4 | Template page refresh uses established design patterns |
| UI-BUDGETS-01 | Phase 4 | Budget list and detail page refresh uses established design patterns |
| UI-QUICKADD-01 | Phase 4 | Quick-add page refresh uses established design patterns |
| UI-SETTINGS-01 | Phase 4 | Settings page refresh uses established design patterns |
| UI-RESPONSIVE-01 | Phase 1, 4 | Responsive foundation set in Phase 1; verified across all pages in Phase 4 |

**Coverage: 13/13 active requirements mapped. No orphans.**

## Progress

**Execution Order:**
Phases execute in numeric order: 1 -> 2 -> 3 -> 4

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Design Foundation and Primitives | 2/2 | Complete    | 2026-03-16 |
| 2. Dashboard Charts and Layout | 3/3 | Complete   | 2026-03-16 |
| 3. Collapsible Dashboard Sections | 0/2 | Planning complete | - |
| 4. Full-App Design Consistency | 0/TBD | Not started | - |