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

✅ v1.0 UI Polish (Phases 1-4) - SHIPPED 2026-03-12

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/2 plans complete

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, 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:

• 03-00-PLAN.md — Wave 0 test stub files
• 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: 2/2 plans complete

Plans:

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

---

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: 2/2 plans complete

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: 2/2 plans complete

Plans:

• 06-01-PLAN.md — Template API client, useTemplate hook, TemplatePage with add/remove/reorder, routing and i18n
• 06-02-PLAN.md — Replace BudgetSetup with template-based month picker, remove copy-from-previous, item tier badges in trackers

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: 1/2 plans executed

Plans:

• 07-01-PLAN.md — DB migration, QuickAddItem model, CRUD queries, REST handlers at /api/quick-add
• 07-02-PLAN.md — QuickAddPage management UI, QuickAddPicker in dashboard, sidebar nav and routing

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	v1.1	2/2	Complete	2026-03-12
6. Template Frontend and Workflow Replacement	v1.1	2/2	Complete	2026-03-12
7. Quick-Add Library	1/2	In Progress		-
8. Layout and Density Rethink	v1.1	0/2	Not started	-