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