chore: complete v1.0 UI/UX Overhaul milestone

.planning/PROJECT.md

@@ -2,11 +2,24 @@
 
 ## What This Is
 
-A personal finance dashboard web app that replaces a basic monthly budget spreadsheet. Users set up income, bills, expenses, debt, and savings categories, create monthly budgets from templates, and track budget vs actual spending with visual charts and summaries. Built as a React SPA with Supabase backend.
+A self-hosted personal budget dashboard that replaces a manual spreadsheet workflow. It tracks monthly budgets with bills, variable expenses, debts, savings, and investments — presented in a dense, visually rich UI with OKLCH pastel colors, three chart types (donut, bar, horizontal bar), collapsible category sections, and consistent design across all 9 pages. Features a smart template system for recurring items, quick-add library for one-off expenses, and auto-generated budgets. Built with Go (backend) + React/TypeScript (frontend) + PostgreSQL.
 
 ## Core Value
 
-Users can see their full monthly financial picture at a glance — income, spending, and what's left — in a visually rich, easy-to-read dashboard.
+Opening the app should feel like opening a beautifully designed personal spreadsheet — clean pastel colors, clear data layout, approachable and visually delightful. The UI IS the product.
+
+## Current State
+
+**Shipped:** v1.0 (UI/UX Overhaul) + prior foundation (auth, CRUD, templates, quick-add)
+
+The app has a complete visual overhaul:
+- OKLCH design system with two-tier category colors and semantic budget status tokens
+- PageShell, StatCard, SummaryStrip shared components for consistent page structure
+- Three chart types (expense donut, income bar, spend horizontal bar) with CSS variable theming
+- URL-based month navigation with MonthNavigator dropdown
+- Collapsible per-category dashboard sections with direction-aware diff and CSS animations
+- All 9 pages upgraded with consistent design, skeleton loading, and i18n
+- Auth pages redesigned with brand presence and OAuth icons
 
 ## Requirements
 
@@ -24,81 +37,86 @@ Users can see their full monthly financial picture at a glance — income, spend
 - ✓ User can set locale and currency in settings — existing
 - ✓ App supports English and German — existing
 - ✓ Dashboard shows summary cards (income, expenses, balance) — existing
-- ✓ Dashboard shows expense breakdown pie chart — existing
-- ✓ Dashboard shows category progress bars — existing
-- ✓ UI-BAR-01: Add bar chart comparing income budget vs actual — Phase 2
-- ✓ UI-HBAR-01: Add horizontal bar chart comparing spend budget vs actual by category type — Phase 2
-- ✓ UI-DONUT-01: Improve donut chart for expense category breakdown with richer styling — Phase 2
+- ✓ UI-DASH-01: Redesign dashboard with hybrid layout — summary cards, charts, and collapsible category sections — v1.0
+- ✓ UI-BAR-01: Bar chart comparing income budget vs actual — v1.0
+- ✓ UI-HBAR-01: Horizontal bar chart comparing spend budget vs actual by category type — v1.0
+- ✓ UI-DONUT-01: Improved donut chart for expense category breakdown with richer styling — v1.0
+- ✓ UI-COLLAPSE-01: Collapsible inline sections on dashboard for each category group — v1.0
+- ✓ UI-DESIGN-01: Redesigned all pages with rich, colorful visual style — v1.0
+- ✓ UI-AUTH-01: Refreshed login and register pages — v1.0
+- ✓ UI-CATEGORIES-01: Refreshed categories page — v1.0
+- ✓ UI-TEMPLATE-01: Refreshed template page — v1.0
+- ✓ UI-BUDGETS-01: Refreshed budget list and budget detail pages — v1.0
+- ✓ UI-QUICKADD-01: Refreshed quick-add page — v1.0
+- ✓ UI-SETTINGS-01: Refreshed settings page — v1.0
+- ✓ UI-RESPONSIVE-01: Desktop-first responsive layout across all pages — v1.0
 
 ### Active
 
-- [ ] UI-DASH-01: Redesign dashboard with hybrid layout — summary cards, charts, and collapsible category sections (income, bills, expenses, debt, savings) with budget/actual columns
-- [ ] UI-COLLAPSE-01: Add collapsible inline sections on dashboard for each category group showing individual line items
-- [ ] UI-DESIGN-01: Redesign all pages with rich, colorful visual style — consistent design language across the app
-- [ ] UI-AUTH-01: Refresh login and register pages
-- [ ] UI-CATEGORIES-01: Refresh categories page
-- [ ] UI-TEMPLATE-01: Refresh template page
-- [ ] UI-BUDGETS-01: Refresh budget list and budget detail pages
-- [ ] UI-QUICKADD-01: Refresh quick-add page
-- [ ] UI-SETTINGS-01: Refresh settings page
-- [ ] UI-RESPONSIVE-01: Desktop-first responsive layout across all pages
+<!-- Next milestone scope. TBD. -->
+
+(No active requirements — next milestone not yet planned)
 
 ### Out of Scope
 
-- New backend features or data model changes — this milestone is UI only
-- Recurring transaction automation — no backend changes
-- Spending alerts or notifications — no backend changes
-- Trend charts over months — future feature, not part of UI overhaul
+- New backend features or data model changes — UI milestone complete, future milestones may add backend
+- Recurring transaction automation — future feature
+- Spending alerts or notifications — future feature
+- Trend charts over months — future feature
 - Mobile-first optimization — desktop first, basic responsiveness only
+- CSV/bank import — future feature
+- Shared/household budgets — future feature
+- Dark mode — light mode pastel system first
 
 ## Context
 
-- **Existing codebase:** React 19 + Vite 8 + Tailwind CSS 4 + Supabase + TanStack Query + Recharts + shadcn/ui (Radix) + i18next
-- **Data model:** Profiles, Categories (6 types), Templates/TemplateItems, Budgets/BudgetItems, QuickAddItems
-- **Architecture:** Three-tier SPA — Pages > Hooks > Supabase. TanStack Query for state. No Redux/Zustand.
-- **Auth:** Supabase auth with RLS policies. Protected/public routes via React Router.
-- **Current UI state:** Functional but basic. shadcn/ui cards and tables. Single pie chart and progress bars on dashboard. Other pages are simple CRUD forms/tables.
-- **Reference image:** Monthly budget spreadsheet with income/bills/expenses/debt/savings sections, budget vs actual columns, bar charts, horizontal bars, and donut chart. Rich colors.
+v1.0 (UI/UX Overhaul) shipped a complete visual transformation across all 9 pages. The design system uses OKLCH color tokens with a two-tier approach (darker text colors for WCAG contrast, lighter fills for charts). PageShell provides consistent page headers. Three chart types replace the old pie chart and progress bars. Collapsible category sections give users drill-down capability on the dashboard. All pages have skeleton loading states and full i18n coverage.
+
+Tech stack: Go 1.25 + React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui + Recharts + PostgreSQL 16. Package manager: bun. Single Docker image via multi-stage build.
 
 ## Constraints
 
-- **Tech stack**: Must use existing stack (React, Tailwind, Recharts, shadcn/ui) — no new frameworks or major dependencies
-- **Backend**: No Supabase schema changes — UI-only modifications
-- **Data model**: Existing types and hooks must be preserved — redesign the presentation layer only
-- **i18n**: All new UI text must have translation keys in both en.json and de.json
+- **Tech stack**: Keep existing Go + React + shadcn/ui + Tailwind + Recharts stack
+- **Design system**: Build on shadcn/ui, customize via CSS variables and Tailwind config
+- **i18n**: All new/changed UI text must have de + en translations
+- **Package manager**: Use bun for frontend
+- **Platform**: Desktop web only — no mobile/tablet optimization
 
 ## Key Decisions
 
 | Decision | Rationale | Outcome |
 |----------|-----------|---------|
-| UI overhaul only, no backend changes | Keep scope focused, ship faster, reduce risk | Pending |
-| Desktop-first layout | Primary use case is desktop; basic responsive for mobile | Pending |
-| Rich & colorful visual style | Match the visual density and appeal of the spreadsheet reference | Pending |
-| Hybrid dashboard (summary + collapsible sections) | Best of both: quick overview with drill-down capability inline | Pending |
-| All three chart types (bar, horizontal bar, donut) | Comprehensive financial visualization like the reference | Pending |
-| Refresh all pages, not just dashboard | Consistent design language throughout the app | Pending |
-| 4-phase roadmap: Foundation > Charts > Collapsibles > Full-app | Build dependency chain from research; design tokens before components, dashboard before other pages | Pending |
-| URL-based month navigation via useMonthParam | Survives refresh and enables sharing; uses ?month=YYYY-MM search param | Phase 2 |
-| 3-column responsive chart grid (md:2, lg:3) | Fits donut + 2 bar charts; collapses gracefully on smaller screens | Phase 2 |
-| DashboardContent as inner component pattern | Separates month selection/empty state from data-dependent chart rendering | Phase 2 |
+| UI overhaul only, no backend changes | Keep scope focused, ship faster, reduce risk | ✓ Good |
+| Desktop-first layout | Primary use case is desktop; basic responsive for mobile | ✓ Good |
+| Rich & colorful visual style | Match the visual density and appeal of the spreadsheet reference | ✓ Good |
+| Hybrid dashboard (summary + collapsible sections) | Best of both: quick overview with drill-down capability inline | ✓ Good |
+| All three chart types (bar, horizontal bar, donut) | Comprehensive financial visualization like the reference | ✓ Good |
+| Refresh all pages, not just dashboard | Consistent design language throughout the app | ✓ Good |
+| 4-phase roadmap: Foundation > Charts > Collapsibles > Full-app | Design tokens before components, dashboard before other pages | ✓ Good |
+| URL-based month navigation via useMonthParam | Survives refresh and enables sharing; uses ?month=YYYY-MM search param | ✓ Good |
+| 3-column responsive chart grid (md:2, lg:3) | Fits donut + 2 bar charts; collapses gracefully on smaller screens | ✓ Good |
+| DashboardContent as inner component pattern | Separates month selection/empty state from data-dependent chart rendering | ✓ Good |
+| Two-tier OKLCH category colors | Darker text (~0.55) for WCAG contrast, lighter fills (~0.65-0.70) for charts | ✓ Good |
+| CategorySection controlled open/onOpenChange pattern | Parent owns state for smart expand defaults and month-change reset | ✓ Good |
+| Auth card accent pattern (border-t-4 + favicon logo) | Consistent brand presence without heavy custom design | ✓ Good |
+| Direction-aware diff for all 6 category types | Spending over when actual > budget; income/saving over when actual < budget | ✓ Good |
 
-## Traceability
+## Evolution
 
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| UI-DASH-01 | Phase 1, 2, 3 | Pending |
-| UI-BAR-01 | Phase 2 | Validated |
-| UI-HBAR-01 | Phase 2 | Validated |
-| UI-DONUT-01 | Phase 2 | Validated |
-| UI-COLLAPSE-01 | Phase 3 | Pending |
-| UI-DESIGN-01 | Phase 1, 4 | Pending |
-| UI-AUTH-01 | Phase 4 | Pending |
-| UI-CATEGORIES-01 | Phase 4 | Pending |
-| UI-TEMPLATE-01 | Phase 4 | Pending |
-| UI-BUDGETS-01 | Phase 4 | Pending |
-| UI-QUICKADD-01 | Phase 4 | Pending |
-| UI-SETTINGS-01 | Phase 4 | Pending |
-| UI-RESPONSIVE-01 | Phase 1, 4 | Pending |
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd:transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
 
 ---
-*Last updated: 2026-03-16 after Phase 2*
+*Last updated: 2026-03-24 after v1.0 UI/UX Overhaul milestone completion*