SimpleFinanceDash/.planning/ROADMAP.md

# Roadmap: SimpleFinanceDash

## Milestones

- ✅ **v1.0 UI Polish** - Phases 1-4 (shipped 2026-03-12)
- 🚧 **v1.1 Usability and Templates** - Phases 5-8 (in progress)

## Phases

<details>
<summary>✅ v1.0 UI Polish (Phases 1-4) - SHIPPED 2026-03-12</summary>

### 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:
- [x] 01-01-PLAN.md — CSS token foundation, palette.ts module, and test infrastructure
- [x] 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/2 plans complete

Plans:
- [x] 02-01-PLAN.md — Auth screen branding (gradient background, wordmark, alert errors)
- [x] 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, or budget create 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:** 4/4 plans complete

Plans:
- [x] 03-00-PLAN.md — Wave 0 test stub files
- [x] 03-01-PLAN.md — InlineEditCell pencil icon + save callbacks, form submit spinners
- [x] 03-02-PLAN.md — Delete confirmation dialog, empty states for Dashboard and Categories
- [x] 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:** 2/2 plans complete

Plans:
- [x] 04-01-PLAN.md — TDD: formatCurrency locale parameter fix (FIX-01)
- [x] 04-02-PLAN.md — Chart tooltip wiring and locale threading (IXTN-04)

</details>

---

### v1.1 Usability and Templates (In Progress)

**Milestone Goal:** Replace the blunt "copy from previous month" workflow with a smart template system that understands fixed, variable, and one-off expenses. Add a quick-add library for saved one-off categories. Rethink the dashboard layout for denser, spreadsheet-like data presentation.

#### Phase 5: Template Data Model and API
**Goal**: The backend has a first-class template system — new DB tables, migrations, and REST endpoints — that lets the app store user templates, classify items by tier, and generate budgets from templates programmatically
**Depends on**: Phase 4
**Requirements**: TMPL-01, TMPL-02, TMPL-04
**Success Criteria** (what must be TRUE):
  1. A budget item can be tagged as fixed, variable, or one-off — the tag is stored in the database and returned by the existing budget item API
  2. A user's template can be created and fetched via the API — it contains fixed items (with amounts) and variable items (category only, no amount)
  3. One-off items are excluded from template contents — the API never includes them in template responses
  4. The template API endpoints are documented and return correct data for all three item tiers
**Plans:** 1/2 plans executed

Plans:
- [ ] 05-01-PLAN.md — DB migration (item_tier enum, templates/template_items tables) + Go models + query functions
- [ ] 05-02-PLAN.md — HTTP handlers for template CRUD, budget generation endpoint, route wiring

#### Phase 6: Template Frontend and Workflow Replacement
**Goal**: Users can manage their template on a dedicated page, navigate to any month and get a budget auto-generated from their template, and the old "copy from previous month" flow is gone
**Depends on**: Phase 5
**Requirements**: TMPL-03, TMPL-05, TMPL-06
**Success Criteria** (what must be TRUE):
  1. Navigating to a month with no budget automatically generates one from the user's template — fixed items appear with their amounts, variable items appear with blank amounts
  2. The template management page lets the user add, remove, and reorder fixed and variable items without leaving the page
  3. When adding a budget item (fixed or variable), the user can tag it inline as fixed, variable, or one-off
  4. The "copy from previous month" button is no longer visible anywhere in the app
**Plans**: TBD

Plans:
- [ ] 06-01: Item type tagging UI — inline fixed/variable/one-off selector on add/edit forms
- [ ] 06-02: Template management page — add, remove, reorder items with live preview
- [ ] 06-03: Auto-generate budget on navigate — wire frontend to generation endpoint, remove copy-from-previous

#### Phase 7: Quick-Add Library
**Goal**: Users can save frequently-used one-off expense categories to a personal library and insert them into any month's budget in one click, eliminating re-entry friction for recurring one-offs like pharmacy visits
**Depends on**: Phase 5
**Requirements**: QADD-01, QADD-02, QADD-03
**Success Criteria** (what must be TRUE):
  1. A user can save a one-off expense category (with an icon) to their quick-add library from the budget item add flow
  2. When adding a one-off item, the user can browse their quick-add library and select a saved category — the item populates with that category and icon
  3. The quick-add library management page lets the user add, edit, and remove saved categories
**Plans**: TBD

Plans:
- [ ] 07-01: Quick-add library backend — DB table, API endpoints for saved categories
- [ ] 07-02: Quick-add library frontend — management page and picker UI in add-item flow

#### Phase 8: Layout and Density Rethink
**Goal**: The dashboard looks and feels like a beautifully designed spreadsheet — flat containers, tight rows, no wasted chrome — and maximizes the data visible on a desktop screen without scrolling
**Depends on**: Phase 6
**Requirements**: LYOT-01, LYOT-02, LYOT-03, LYOT-04, LYOT-05
**Success Criteria** (what must be TRUE):
  1. Dashboard sections use flat, lightweight containers — heavy bordered card chrome is replaced by integrated section boundaries that recede visually
  2. Table rows have tighter padding — more rows are visible on a standard desktop viewport without scrolling compared to the current layout
  3. There is no top padding gap above colored section headers — the header color reaches the container edge
  4. The dashboard grid layout is optimized for desktop — the most important data is visible above the fold on a 1440px screen
**Plans**: TBD

Plans:
- [ ] 08-01: Container and card chrome rework — flatten section containers, eliminate top padding above headers
- [ ] 08-02: Row density and grid layout — tighten table rows, optimize desktop grid proportions

## Progress

**Execution Order:**
Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8

| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 1. Design Token Foundation | v1.0 | 2/2 | Complete | 2026-03-11 |
| 2. Layout and Brand Identity | v1.0 | 2/2 | Complete | 2026-03-12 |
| 3. Interaction Quality and Completeness | v1.0 | 4/4 | Complete | 2026-03-12 |
| 4. Chart Polish and Bug Fixes | v1.0 | 2/2 | Complete | 2026-03-12 |
| 5. Template Data Model and API | 1/2 | In Progress|  | - |
| 6. Template Frontend and Workflow Replacement | v1.1 | 0/3 | Not started | - |
| 7. Quick-Add Library | v1.1 | 0/2 | Not started | - |
| 8. Layout and Density Rethink | v1.1 | 0/2 | Not started | - |