From 43877959471134acdeea6b9c29a495bb245b00e7 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Mon, 16 Mar 2026 11:48:16 +0100 Subject: [PATCH] docs: create UI/UX overhaul roadmap with 4-phase structure Map all 13 active requirements to a foundation-first delivery sequence: design primitives, dashboard charts, collapsible sections, then full-app consistency. Co-Authored-By: Claude Opus 4.6 --- .planning/PROJECT.md | 59 +++++++++++------- .planning/ROADMAP.md | 138 +++++++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 61 +++++++++++++++++++ 3 files changed, 238 insertions(+), 20 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 7f1e46b..a399b2c 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -29,19 +29,19 @@ Users can see their full monthly financial picture at a glance — income, spend ### Active -- [ ] Redesign dashboard with hybrid layout — summary cards, charts, and collapsible category sections (income, bills, expenses, debt, savings) with budget/actual columns -- [ ] Add bar chart comparing income budget vs actual -- [ ] Add horizontal bar chart comparing spend budget vs actual by category type -- [ ] Improve donut chart for expense category breakdown with richer styling -- [ ] Add collapsible inline sections on dashboard for each category group showing individual line items -- [ ] Redesign all pages with rich, colorful visual style — consistent design language across the app -- [ ] Refresh login and register pages -- [ ] Refresh categories page -- [ ] Refresh template page -- [ ] Refresh budget list and budget detail pages -- [ ] Refresh quick-add page -- [ ] Refresh settings page -- [ ] Desktop-first responsive layout across all pages +- [ ] UI-DASH-01: Redesign dashboard with hybrid layout — summary cards, charts, and collapsible category sections (income, bills, expenses, debt, savings) with budget/actual columns +- [ ] UI-BAR-01: Add bar chart comparing income budget vs actual +- [ ] UI-HBAR-01: Add horizontal bar chart comparing spend budget vs actual by category type +- [ ] UI-DONUT-01: Improve donut chart for expense category breakdown with richer styling +- [ ] UI-COLLAPSE-01: Add collapsible inline sections on dashboard for each category group showing individual line items +- [ ] UI-DESIGN-01: Redesign all pages with rich, colorful visual style — consistent design language across the app +- [ ] UI-AUTH-01: Refresh login and register pages +- [ ] UI-CATEGORIES-01: Refresh categories page +- [ ] UI-TEMPLATE-01: Refresh template page +- [ ] UI-BUDGETS-01: Refresh budget list and budget detail pages +- [ ] UI-QUICKADD-01: Refresh quick-add page +- [ ] UI-SETTINGS-01: Refresh settings page +- [ ] UI-RESPONSIVE-01: Desktop-first responsive layout across all pages ### Out of Scope @@ -71,12 +71,31 @@ Users can see their full monthly financial picture at a glance — income, spend | Decision | Rationale | Outcome | |----------|-----------|---------| -| UI overhaul only, no backend changes | Keep scope focused, ship faster, reduce risk | — Pending | -| Desktop-first layout | Primary use case is desktop; basic responsive for mobile | — Pending | -| Rich & colorful visual style | Match the visual density and appeal of the spreadsheet reference | — Pending | -| Hybrid dashboard (summary + collapsible sections) | Best of both: quick overview with drill-down capability inline | — Pending | -| All three chart types (bar, horizontal bar, donut) | Comprehensive financial visualization like the reference | — Pending | -| Refresh all pages, not just dashboard | Consistent design language throughout the app | — Pending | +| UI overhaul only, no backend changes | Keep scope focused, ship faster, reduce risk | Pending | +| Desktop-first layout | Primary use case is desktop; basic responsive for mobile | Pending | +| Rich & colorful visual style | Match the visual density and appeal of the spreadsheet reference | Pending | +| Hybrid dashboard (summary + collapsible sections) | Best of both: quick overview with drill-down capability inline | Pending | +| All three chart types (bar, horizontal bar, donut) | Comprehensive financial visualization like the reference | Pending | +| Refresh all pages, not just dashboard | Consistent design language throughout the app | Pending | +| 4-phase roadmap: Foundation > Charts > Collapsibles > Full-app | Build dependency chain from research; design tokens before components, dashboard before other pages | Pending | + +## Traceability + +| Requirement | Phase | Status | +|-------------|-------|--------| +| UI-DASH-01 | Phase 1, 2, 3 | Pending | +| UI-BAR-01 | Phase 2 | Pending | +| UI-HBAR-01 | Phase 2 | Pending | +| UI-DONUT-01 | Phase 2 | Pending | +| UI-COLLAPSE-01 | Phase 3 | Pending | +| UI-DESIGN-01 | Phase 1, 4 | Pending | +| UI-AUTH-01 | Phase 4 | Pending | +| UI-CATEGORIES-01 | Phase 4 | Pending | +| UI-TEMPLATE-01 | Phase 4 | Pending | +| UI-BUDGETS-01 | Phase 4 | Pending | +| UI-QUICKADD-01 | Phase 4 | Pending | +| UI-SETTINGS-01 | Phase 4 | Pending | +| UI-RESPONSIVE-01 | Phase 1, 4 | Pending | --- -*Last updated: 2026-03-16 after initialization* +*Last updated: 2026-03-16 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..01f5b5e --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,138 @@ +# 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 +- [ ] **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**: TBD + +Plans: +- [ ] 01-01: TBD +- [ ] 01-02: TBD + +### Phase 2: Dashboard Charts and Layout +**Goal**: Deliver the full dashboard chart suite — donut, vertical bar, and horizontal bar — inside a responsive ChartPanel, 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 3.8.0 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**: TBD + +Plans: +- [ ] 02-01: TBD +- [ ] 02-02: TBD + +### 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**: TBD + +Plans: +- [ ] 03-01: TBD + +### 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 | 0/TBD | Not started | - | +| 2. Dashboard Charts and Layout | 0/TBD | Not started | - | +| 3. Collapsible Dashboard Sections | 0/TBD | Not started | - | +| 4. Full-App Design Consistency | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..000e500 --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,61 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-03-16) + +**Core value:** Users can see their full monthly financial picture at a glance — income, spending, and what's left — in a visually rich, easy-to-read dashboard. +**Current focus:** Phase 1 — Design Foundation and Primitives + +## Current Position + +Phase: 1 of 4 (Design Foundation and Primitives) +Plan: 0 of TBD in current phase +Status: Ready to plan +Last activity: 2026-03-16 — Roadmap created + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: - +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: - +- Trend: - + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- [Roadmap]: 4-phase structure derived from research — foundation before features, dashboard before other pages, charts before collapsibles +- [Roadmap]: All research flags set to NO — no `/gsd:research-phase` needed before any phase + +### Pending Todos + +None yet. + +### Blockers/Concerns + +- shadcn `chart.tsx` requires manual `initialDimension` patch after CLI install (issue #9892) — must be applied in Phase 1 before any chart work +- WCAG contrast audit needed for bumped OKLCH chroma values during Phase 1 token work + +## Session Continuity + +Last session: 2026-03-16 +Stopped at: Roadmap and state files created, ready for Phase 1 planning +Resume file: None