SimpleFinanceDash/.planning/ROADMAP.md

Roadmap: SimpleFinanceDash UI Polish

Overview

This milestone transforms a functional but visually generic finance dashboard into a cohesive, pastel-themed experience. The work follows a strict dependency order: establish the token system first so every subsequent change produces consistent results, then polish structural surfaces (login, sidebar, layout), then add interaction quality and empty states, then finalize charts which depend on all prior work. Skipping this order is the primary failure mode for visual polish projects.

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 Token Foundation - Establish the pastel CSS variable system and semantic color tokens that all subsequent phases depend on (completed 2026-03-11)
• Phase 2: Layout and Brand Identity - Polish the surfaces users see on every page load — login, sidebar, card headers, typography
• Phase 3: Interaction Quality and Completeness - Add loading, empty, and error states plus inline edit affordances to eliminate the "unfinished" feeling
• Phase 4: Chart Polish and Bug Fixes - Finalize chart styling with semantic colors, formatted tooltips, and fix the currency locale bug

Phase Details

Phase 1: Design Token Foundation

Goal: The app has a live pastel color system where all shadcn components read from intentionally designed oklch tokens, category colors come from a single source of truth, and shared inline edit infrastructure is extracted before visual work diverges it further Depends on: Nothing (first phase) Requirements: DSGN-01, DSGN-02, DSGN-03, DSGN-04, DSGN-05, FIX-02 Success Criteria (what must be TRUE):

1. Every shadcn component (buttons, cards, badges, inputs) displays in pastel tones — no neutral grey/white zero-chroma colors remain in index.css
2. Dashboard card header gradients use a unified pastel family — Bills, Variable Expenses, Debt, Savings, and Investments sections each have a distinct but harmonious pastel color
3. FinancialOverview and AvailableBalance render as visually dominant hero elements with clear typographic hierarchy above secondary content
4. Amount values across all tables and summaries show green for positive, destructive red for negative, and amber for over-budget — applied consistently
5. A single lib/palette.ts file exists as the source of truth for all category-to-color mappings; InlineEditCell.tsx is extracted as a shared component replacing three duplicated local definitions Plans: 2/2 plans complete Plans:

• 01-01-PLAN.md — CSS token foundation, palette.ts module, and test infrastructure
• 01-02-PLAN.md — Component wiring, InlineEditCell extraction, and visual verification

Phase 2: Layout and Brand Identity

Goal: Users encounter a visually branded, polished experience on every high-visibility surface — login page, sidebar, and dashboard layout — establishing the perceptual quality bar for the entire app Depends on: Phase 1 Requirements: AUTH-01, AUTH-02, AUTH-03, AUTH-04, NAV-01, NAV-02, NAV-03, NAV-04 Success Criteria (what must be TRUE):

1. The login and register screens have a pastel gradient background and a styled app wordmark — not a plain white card on a white screen
2. Auth form validation errors display with styled alert blocks and error icons, not plain text
3. The sidebar has a pastel background visually distinct from the main content area, with a branded typographic treatment for the app name
4. The active navigation item has a clearly visible color indicator — clicking a nav item produces a visible selected state
5. The sidebar can be collapsed via a toggle button, reducing screen space usage on smaller layouts Plans: 2 plans Plans:

• 02-01-PLAN.md — Auth screen branding (gradient background, wordmark, alert errors)
• 02-02-PLAN.md — Sidebar polish (wordmark, active indicator, collapse trigger)

Phase 3: Interaction Quality and Completeness

Goal: Every user action and app state has appropriate visual feedback — loading states, empty states, edit affordances, and delete confirmations — so the app feels complete and trustworthy Depends on: Phase 2 Requirements: IXTN-01, IXTN-02, IXTN-03, IXTN-05, STATE-01, STATE-02, STATE-03 Success Criteria (what must be TRUE):

1. Submitting a login, register, budget create, or budget edit form shows a spinner on the button — the user knows the request is in flight (Note: Budget Edit form does not exist yet; spinner covers 3 existing forms — Login, Register, Budget Create)
2. Hovering over an inline-editable row reveals a pencil icon, making the edit affordance discoverable before clicking
3. After saving an inline edit, the row briefly flashes a confirmation color, confirming the save completed
4. Attempting to delete a category triggers a confirmation dialog before the deletion executes
5. A user with no budgets sees a designed empty state with a clear CTA on the dashboard; a user with no categories sees the same on the categories page; loading skeletons use pastel-tinted backgrounds matching their section Plans: 4 plans Plans:

• 03-00-PLAN.md — Wave 0 test stub files (BudgetSetup, CategoriesPage, DashboardPage, BillsTracker)
• 03-01-PLAN.md — InlineEditCell pencil icon + save callbacks, form submit spinners
• 03-02-PLAN.md — Delete confirmation dialog, empty states for Dashboard and Categories
• 03-03-PLAN.md — Row flash wiring in trackers, pastel-tinted loading skeletons

Phase 4: Chart Polish and Bug Fixes

Goal: Charts look polished and informative with semantic category colors, correctly formatted currency tooltips, and the currency locale bug fixed so values display in the user's preferred locale Depends on: Phase 3 Requirements: IXTN-04, FIX-01 Success Criteria (what must be TRUE):

1. All chart fills (donut slices, bar segments) use the semantic category colors from lib/palette.ts — "Bills" is the same color in the donut chart as it is in the FinancialOverview table
2. Chart tooltips display values formatted with the budget's currency (e.g., "1,234.56" not "1234.56")
3. The formatCurrency function uses the user's locale preference from their settings instead of the hardcoded de-DE — an English-locale user sees their numbers formatted correctly Plans: TBD

Progress

Execution Order: Phases execute in numeric order: 1 -> 2 -> 3 -> 4

Phase	Plans Complete	Status	Completed
1. Design Token Foundation	2/2	Complete	2026-03-11
2. Layout and Brand Identity	0/2	In progress	-
3. Interaction Quality and Completeness	0/4	Not started	-
4. Chart Polish and Bug Fixes	0/TBD	Not started	-