142 lines
10 KiB
Markdown
142 lines
10 KiB
Markdown
# 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**: 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 | 0/3 | Not started | - |
|