docs(01): capture phase context

.planning/phases/01-design-token-foundation/01-CONTEXT.md

@@ -0,0 +1,99 @@
+# Phase 1: Design Token Foundation - Context
+
+**Gathered:** 2026-03-11
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Establish the pastel CSS variable system and semantic color tokens that all subsequent phases depend on. Replace zero-chroma neutral shadcn tokens with intentional pastel oklch values, create `lib/palette.ts` as the single source of truth for category-to-color mappings, unify card header gradients, establish typography hierarchy for hero elements, apply consistent amount coloring, and extract `InlineEditCell.tsx` from three duplicated definitions.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Pastel palette direction
+- Rainbow pastels: distinct pastel hue per category type, unified lightness and saturation across all hues
+- Base shadcn tokens (primary, secondary, accent, muted, ring) carry a soft lavender tint — not plain grey
+- App background gets a very subtle lavender tint (e.g., `oklch(0.98 0.005 290)`); cards stay pure white so they float on the tinted surface
+- Chart colors (chart-1 through chart-5) match the category colors from palette.ts — same color in charts as in tables
+
+### Category color mapping
+- Natural finance conventions for hue assignments:
+  - income: soft green (money in)
+  - bills: soft blue (recurring, stable)
+  - variable_expense: soft amber (variable, caution)
+  - debt: soft rose (obligation)
+  - saving: soft violet (aspirational)
+  - investment: soft pink (growth)
+  - carryover: soft sky (neutral carry-forward)
+- 3 shades per category in palette.ts: light (row backgrounds), medium (header gradients, badges), base (chart fills, text accents)
+- Card header gradients go from category light to category medium (within the same hue)
+- FinancialOverview table rows each tinted with their category's light shade (per-row category color)
+
+### Hero element prominence
+- FinancialOverview and AvailableBalance get larger titles (text-2xl font-semibold vs text-lg font-medium on regular cards) and more generous padding (p-6 vs p-4)
+- AvailableBalance center amount uses text-3xl font-bold, color-coded: green when positive, destructive red when negative
+- Small muted-foreground label ("Available") sits below the center amount in the donut
+- FinancialOverview header uses a multi-pastel gradient (e.g., sky-light via lavender-light to green-light) to signal it represents all categories
+
+### Amount coloring rules
+- Amber triggers when actual_amount > budgeted_amount for expense categories (bills, variable_expense, debt). Exactly on budget = normal (no amber)
+- Only the actual column gets colored; budget column stays neutral
+- Income: any positive actual shows green (money received is always positive). Zero actual stays neutral
+- Amount coloring applies everywhere consistently: FinancialOverview summary rows AND individual item rows in BillsTracker, VariableExpenses, DebtTracker
+- Remaining/Available row: green when positive, destructive red when negative
+
+### Claude's Discretion
+- Exact oklch values for all palette colors (lightness, chroma, hue angles) — as long as they feel pastel and harmonious
+- Loading skeleton tint colors
+- Exact spacing values and font weight choices beyond the hero vs regular distinction
+- InlineEditCell extraction approach (props interface design, where to place the shared component)
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "Opening the app should feel like opening a beautifully designed personal spreadsheet" (from PROJECT.md core value)
+- FinancialOverview rows should look like a color-coded spreadsheet — each category row has its own pastel tint
+- The donut chart center amount should give instant visual signal of budget health via color
+- Card headers with category gradients create visual anchoring — you know which section you're in by color
+
+</specifics>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- 18 shadcn/ui components already installed (button, card, dialog, input, select, table, tabs, sidebar, avatar, badge, chart, separator, dropdown-menu, scroll-area, sheet, skeleton, spinner, tooltip)
+- `cn()` utility in `lib/utils.ts` for className merging
+- `formatCurrency()` in `lib/format.ts` — used across all components (locale fix is Phase 4)
+- Geist Variable font already loaded via @fontsource
+
+### Established Patterns
+- CSS variables in `index.css` `:root` block using oklch color space — replace values in place
+- `@theme inline` block maps CSS vars to Tailwind `--color-*` tokens
+- Card + CardHeader + CardContent pattern used consistently across all dashboard components
+- Components import from `@/components/ui/*` and `@/lib/*`
+
+### Integration Points
+- `index.css` `:root` — all shadcn CSS variables live here, replace neutral oklch with pastel oklch
+- `lib/palette.ts` — new file, imported by FinancialOverview, AvailableBalance, BillsTracker, VariableExpenses, DebtTracker, ExpenseBreakdown, and eventually charts (Phase 4)
+- `InlineEditCell.tsx` — extract from BillsTracker.tsx (lines 59-110), then import in BillsTracker, VariableExpenses, DebtTracker
+- Card header gradients — currently hardcoded in each component's `<CardHeader className="...">`, switch to palette.ts references
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 01-design-token-foundation*
+*Context gathered: 2026-03-11*