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.

- [x] **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**: TBD

### 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
  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**: TBD

### 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/TBD | Not started | - |
| 3. Interaction Quality and Completeness | 0/TBD | Not started | - |
| 4. Chart Polish and Bug Fixes | 0/TBD | Not started | - |