SimpleFinanceDash/.planning/phases/05-design-system-token-rework/05-CONTEXT.md

Phase 5: Design System Token Rework - Context

Gathered: 2026-04-20 Status: Ready for planning

## Phase Boundary

Users see a sharp, minimal, clearly pastel UI across every page — the visual foundation that all subsequent phases build on. This phase modifies design tokens (CSS variables), adjusts spacing utilities across all 9 pages, and overrides third-party component styles. No new features, no new components — purely visual token and spacing changes.

## Implementation Decisions

Corner Radius Strategy

• All elements get 0px border radius — truly sharp corners everywhere
• Implementation via single --radius: 0 token change in src/index.css (cascades to all shadcn components)
• No exceptions for avatars, badges, or any element
• Third-party components (Recharts bars, Sonner toasts) overridden via CSS selectors to force 0 radius

Pastel Color Refinement

• Increase chroma on category fill colors to 0.22+ for visible colorful pop against white backgrounds
• Keep the two-tier color system: text colors at ~0.55L for WCAG 4.5:1 contrast, fill colors lighter/more saturated
• Slightly warm the base UI colors: background chroma from 0.005→0.01 for subtle warmth
• Align chart colors with category fill tokens directly — remove separate --color-chart-* variables and use --color-*-fill tokens in charts

Spacing & Layout Strategy

• Increase section gaps: gap-4→gap-6, gap-6→gap-8 across all pages
• Increase card internal padding: p-4→p-6 for breathing room
• Keep existing max-w-7xl container constraint
• Standardize all page headers to mb-6 + section gaps to gap-8 for consistent rhythm

Claude's Discretion

• Exact OKLCH chroma/lightness values for category fills (as long as they're 0.22+ chroma and pass WCAG)
• Order of page updates during implementation
• Whether to create a spacing utility class or apply changes inline

<code_context>

Existing Code Insights

Reusable Assets

• src/index.css — single file with all design tokens (@theme inline block), --radius: 0.625rem is the token to change
• src/lib/palette.ts — category color references using CSS variables (no changes needed, references tokens)
• shadcn/ui components in src/components/ui/ — all use rounded-* classes that derive from --radius

Established Patterns

• OKLCH color system already in place with hue-based category differentiation
• Two-tier category colors: text (L=0.55, C=0.16-0.18) and fill (L=0.65-0.70, C=0.18-0.20)
• Tailwind CSS 4 with @theme inline for CSS variable definitions
• 71 occurrences of rounded/radius across 27 source files

Integration Points

• src/index.css --radius token controls all shadcn component rounding
• Chart components (SpendBarChart, IncomeBarChart, ExpenseDonutChart) reference --color-chart-* variables
• 9 pages to audit: Dashboard, BudgetList, BudgetDetail, Template, Categories, QuickAdd, Settings, Login, Register

</code_context>

## Specific Ideas

• Success criteria explicitly requires visual pass of all 9 pages confirming no regressions
• Category color swatches must be "visibly colorful against white backgrounds" — not washed-out
• "No pill buttons, no rounded cards, no rounded inputs visible anywhere"

## Deferred Ideas

None — discussion stayed within phase scope