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.

• Phase 1: Design Foundation and Primitives - Install shadcn primitives, extend color tokens, build PageShell and StatCard/SummaryStrip
• 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:

• 01-01-PLAN.md — Install shadcn primitives (chart + collapsible), extend OKLCH color tokens, add i18n keys
• 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: 3 plans

Plans:

• 04-01-PLAN.md — Redesign auth pages (Login, Register) with brand presence, muted background, card accent, OAuth SVG icons
• 04-02-PLAN.md — Upgrade CRUD pages (Categories, Template, QuickAdd, Settings) with PageShell, skeletons, group header accents
• 04-03-PLAN.md — Upgrade budget pages (BudgetList, BudgetDetail) with semantic tokens, direction-aware diff, locale-aware months, skeletons

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	1/2	In Progress
4. Full-App Design Consistency	2/3	In Progress