From e5637511d7ae5d28c1fd3937ca2067275c699e08 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Mon, 20 Apr 2026 16:53:20 +0200 Subject: [PATCH] docs(05): create phase 5 design system token rework plans 3 plans across 2 waves covering DS-01, DS-02, DS-03: - Plan 01: Token edits (radius, colors, chart vars) + chart components - Plan 02: Shared component rounded-* removal + spacing upgrades - Plan 03: Per-page sweep (9 pages) + visual verification checkpoint Co-Authored-By: Claude Opus 4.6 --- .planning/ROADMAP.md | 8 +- .../05-01-PLAN.md | 219 +++++++++++++++ .../05-02-PLAN.md | 178 +++++++++++++ .../05-03-PLAN.md | 249 ++++++++++++++++++ 4 files changed, 652 insertions(+), 2 deletions(-) create mode 100644 .planning/phases/05-design-system-token-rework/05-01-PLAN.md create mode 100644 .planning/phases/05-design-system-token-rework/05-02-PLAN.md create mode 100644 .planning/phases/05-design-system-token-rework/05-03-PLAN.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index a5580ae..9d47bf2 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -29,7 +29,11 @@ Decimal phases appear between their surrounding integers in numeric order. 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**: TBD +**Plans:** 3 plans +Plans: +- [ ] 05-01-PLAN.md — Design tokens (radius, colors, chart vars) and chart component Bar radius updates +- [ ] 05-02-PLAN.md — Shared component rounded-* removal and spacing upgrades (PageShell, DashboardSkeleton, CategorySection, ChartEmptyState, QuickAddPicker) +- [ ] 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 @@ -109,7 +113,7 @@ Phases execute in numeric order: 5 → 6 → 7 → 8 → 9 | Phase | Plans Complete | Status | Completed | |-------|----------------|--------|-----------| -| 5. Design System Token Rework | 0/? | Not started | - | +| 5. Design System Token Rework | 0/3 | Planned | - | | 6. Preset Data, First-Run Detection, DB Safety | 0/? | Not started | - | | 7. Setup Wizard | 0/? | Not started | - | | 8. Auto-Budget Creation | 0/? | Not started | - | diff --git a/.planning/phases/05-design-system-token-rework/05-01-PLAN.md b/.planning/phases/05-design-system-token-rework/05-01-PLAN.md new file mode 100644 index 0000000..763231d --- /dev/null +++ b/.planning/phases/05-design-system-token-rework/05-01-PLAN.md @@ -0,0 +1,219 @@ +--- +phase: 05-design-system-token-rework +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - src/index.css + - src/components/dashboard/charts/SpendBarChart.tsx + - src/components/dashboard/charts/IncomeBarChart.tsx + - src/components/dashboard/charts/ExpenseDonutChart.tsx +autonomous: true +requirements: + - DS-01 + - DS-02 + +must_haves: + truths: + - "--radius token is 0 in index.css, cascading sharp corners to all shadcn components" + - "Category fill colors have chroma >= 0.22 making them visibly colorful" + - "--color-chart-* variables are deleted from index.css" + - "Chart bars render with 0 radius (no rounded caps)" + - "CSS overrides exist for Recharts rectangles and Sonner toasts" + artifacts: + - path: "src/index.css" + provides: "Design token source of truth with --radius: 0, raised fill chromas, removed chart vars, third-party overrides" + contains: "--radius: 0" + - path: "src/components/dashboard/charts/SpendBarChart.tsx" + provides: "Spend bar chart with sharp bars" + contains: "radius={0}" + - path: "src/components/dashboard/charts/IncomeBarChart.tsx" + provides: "Income bar chart with sharp bars" + contains: "radius={0}" + - path: "src/components/dashboard/charts/ExpenseDonutChart.tsx" + provides: "Donut chart legend with square color dots" + key_links: + - from: "src/index.css" + to: "all shadcn components" + via: "--radius: 0 token cascade" + pattern: "--radius: 0" + - from: "src/index.css" + to: "chart components" + via: "--color-*-fill CSS variables" + pattern: "color-.*-fill" +--- + + +Edit design tokens in src/index.css (radius, colors, chart var removal, third-party overrides) and update chart component Bar radius props to 0. + +Purpose: Establish the sharp-cornered, vibrant-pastel visual foundation that cascades to all shadcn components and charts. +Output: Modified index.css with new token values + CSS overrides; 3 chart component files with radius={0} and no rounded-full. + + + +@.planning/phases/05-design-system-token-rework/05-RESEARCH.md +@.planning/phases/05-design-system-token-rework/05-PATTERNS.md +@.planning/phases/05-design-system-token-rework/05-UI-SPEC.md + + + +@.planning/ROADMAP.md +@.planning/STATE.md + + + + + +From src/components/dashboard/charts/SpendBarChart.tsx: +```tsx +const chartConfig = { + budgeted: { label: "Budgeted", color: "var(--color-budget-bar-bg)" }, + actual: { label: "Actual", color: "var(--color-muted-foreground)" }, +} satisfies ChartConfig +// Bar radius={4} on both Bar elements +// Cell fill uses var(--color-${entry.type}-fill) -- already correct +``` + +From src/components/dashboard/charts/IncomeBarChart.tsx: +```tsx +const chartConfig = { + budgeted: { label: "Budgeted", color: "var(--color-budget-bar-bg)" }, + actual: { label: "Actual", color: "var(--color-income-fill)" }, +} satisfies ChartConfig +// Bar radius={[4, 4, 0, 0]} on both Bar elements +``` + +From src/components/dashboard/charts/ExpenseDonutChart.tsx: +```tsx +// Line 141: +// Uses var(--color-${entry.type}-fill) for legend dot colors -- already correct +``` + + + + + + + Task 1: Edit design tokens and add CSS overrides in index.css + src/index.css + src/index.css + +Edit src/index.css with these exact changes: + +1. Line 7: Change `--color-background: oklch(0.98 0.005 260)` to `--color-background: oklch(0.98 0.01 260)` (warm background chroma from 0.005 to 0.01). + +2. Lines 52-57: DELETE the entire "Chart Colors" section (6 lines): + ``` + /* Chart Colors */ + --color-chart-1: oklch(0.72 0.14 155); + --color-chart-2: oklch(0.7 0.14 25); + --color-chart-3: oklch(0.72 0.14 50); + --color-chart-4: oklch(0.65 0.16 355); + --color-chart-5: oklch(0.72 0.14 220); + ``` + +3. Lines 65-70: Replace the 6 fill token values with raised chroma (0.22+): + ```css + --color-income-fill: oklch(0.72 0.22 155); + --color-bill-fill: oklch(0.70 0.22 25); + --color-variable-expense-fill: oklch(0.74 0.22 50); + --color-debt-fill: oklch(0.66 0.23 355); + --color-saving-fill: oklch(0.72 0.22 220); + --color-investment-fill: oklch(0.68 0.22 285); + ``` + +4. Line 72: Change `--radius: 0.625rem` to `--radius: 0`. + +5. After the closing `}` of the `@layer base` block (after line 99), add CSS overrides for third-party components: + ```css + /* Third-party radius overrides */ + .recharts-rectangle { + rx: 0; + ry: 0; + } + + [data-sonner-toast] { + border-radius: 0 !important; + } + ``` + + + cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build + + + - src/index.css contains `--radius: 0;` + - src/index.css contains `--color-background: oklch(0.98 0.01 260)` + - src/index.css contains `--color-income-fill: oklch(0.72 0.22 155)` + - src/index.css contains `--color-bill-fill: oklch(0.70 0.22 25)` + - src/index.css contains `--color-variable-expense-fill: oklch(0.74 0.22 50)` + - src/index.css contains `--color-debt-fill: oklch(0.66 0.23 355)` + - src/index.css contains `--color-saving-fill: oklch(0.72 0.22 220)` + - src/index.css contains `--color-investment-fill: oklch(0.68 0.22 285)` + - src/index.css does NOT contain `--color-chart-1` or `--color-chart-2` or `--color-chart-3` or `--color-chart-4` or `--color-chart-5` + - src/index.css contains `.recharts-rectangle` + - src/index.css contains `[data-sonner-toast]` + - `bun run build` exits 0 + + index.css has --radius: 0, raised fill chromas (0.22+), deleted chart vars, warmed background, and CSS overrides for Recharts and Sonner + + + + Task 2: Update chart component Bar radius props and remove hardcoded rounded-full + src/components/dashboard/charts/SpendBarChart.tsx, src/components/dashboard/charts/IncomeBarChart.tsx, src/components/dashboard/charts/ExpenseDonutChart.tsx + src/components/dashboard/charts/SpendBarChart.tsx, src/components/dashboard/charts/IncomeBarChart.tsx, src/components/dashboard/charts/ExpenseDonutChart.tsx + +1. In SpendBarChart.tsx: Find the two ` + + cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build + + + - SpendBarChart.tsx contains `radius={0}` (grep returns 2 matches) + - SpendBarChart.tsx does NOT contain `radius={4}` + - IncomeBarChart.tsx contains `radius={0}` (grep returns 2 matches) + - IncomeBarChart.tsx does NOT contain `radius={[4, 4, 0, 0]}` + - ExpenseDonutChart.tsx does NOT contain `rounded-full` + - ExpenseDonutChart.tsx contains `"inline-block size-3 shrink-0"` + - `bun run build` exits 0 + + All 3 chart components have sharp bars (radius={0}) and the donut legend dot is square (no rounded-full) + + + + + +## Trust Boundaries + +No trust boundaries affected. This plan modifies CSS tokens and SVG presentation props only. No user input handling, no data access, no authentication changes. + +## STRIDE Threat Register + +| Threat ID | Category | Component | Disposition | Mitigation Plan | +|-----------|----------|-----------|-------------|-----------------| +| — | — | — | — | No applicable threats — pure CSS/visual changes | + + + +- `bun run build` passes after both tasks +- grep confirms --radius: 0 in index.css +- grep confirms no --color-chart-* references remain in src/ +- grep confirms radius={0} in both bar chart components + + + +- Token cascade makes all shadcn components sharp-cornered (verified by --radius: 0 in index.css) +- Category fill colors raised to 0.22+ chroma (verified by grep on index.css) +- Chart color duplication eliminated (--color-chart-* deleted, verified by grep) +- Chart bars render with sharp ends (radius={0} in both bar chart files) +- CSS overrides exist for Recharts SVG and Sonner toasts +- Build passes cleanly + + + +After completion, create `.planning/phases/05-design-system-token-rework/05-01-SUMMARY.md` + diff --git a/.planning/phases/05-design-system-token-rework/05-02-PLAN.md b/.planning/phases/05-design-system-token-rework/05-02-PLAN.md new file mode 100644 index 0000000..10b30ee --- /dev/null +++ b/.planning/phases/05-design-system-token-rework/05-02-PLAN.md @@ -0,0 +1,178 @@ +--- +phase: 05-design-system-token-rework +plan: 02 +type: execute +wave: 1 +depends_on: [] +files_modified: + - src/components/shared/PageShell.tsx + - src/components/dashboard/DashboardSkeleton.tsx + - src/components/dashboard/CategorySection.tsx + - src/components/dashboard/charts/ChartEmptyState.tsx + - src/components/QuickAddPicker.tsx +autonomous: true +requirements: + - DS-01 + - DS-03 + +must_haves: + truths: + - "PageShell gap is gap-8 providing generous header-to-content spacing on all pages" + - "All shared component hardcoded rounded-* classes are removed" + - "DashboardSkeleton spacing matches the upgraded gap/space-y values" + - "No pill-shaped skeleton placeholders remain in shared components" + artifacts: + - path: "src/components/shared/PageShell.tsx" + provides: "Layout shell with gap-8 section spacing" + contains: "gap-8" + - path: "src/components/dashboard/DashboardSkeleton.tsx" + provides: "Dashboard loading skeleton with sharp corners and upgraded spacing" + - path: "src/components/dashboard/CategorySection.tsx" + provides: "Category section trigger without rounded-md" + - path: "src/components/dashboard/charts/ChartEmptyState.tsx" + provides: "Chart empty state without rounded-lg" + - path: "src/components/QuickAddPicker.tsx" + provides: "Quick add picker without rounded-sm or rounded-full" + key_links: + - from: "src/components/shared/PageShell.tsx" + to: "all 9 pages" + via: "PageShell wrapper component" + pattern: "gap-8" +--- + + +Remove hardcoded rounded-* classes and upgrade spacing in shared components (PageShell, DashboardSkeleton, CategorySection, ChartEmptyState, QuickAddPicker). + +Purpose: These shared components are used across multiple pages. Fixing them first ensures consistent sharp corners and generous spacing everywhere they appear. +Output: 5 modified component files with no hardcoded rounding and upgraded spacing values. + + + +@.planning/phases/05-design-system-token-rework/05-RESEARCH.md +@.planning/phases/05-design-system-token-rework/05-PATTERNS.md + + + +@.planning/ROADMAP.md +@.planning/STATE.md + + +From src/components/shared/PageShell.tsx (line 15): +```tsx +
gap-8 --> +``` + +From src/components/dashboard/DashboardSkeleton.tsx: +```tsx +// Line 20:
-- gap-8 +// Line 22:
-- gap-6 +// Line 29:
-- gap-8 +// Line 35,43,51: -- remove rounded-md +// Line 59:
-- remove rounded-md +// Lines 63-64: -- remove rounded-full +``` + +From src/components/dashboard/CategorySection.tsx (line 73): +```tsx +