Phase 1: Design Token Foundation - Context

Gathered: 2026-03-11 Status: Ready for planning

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

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

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

<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 Ideas

None — discussion stayed within phase scope

Phase: 01-design-token-foundation Context gathered: 2026-03-11

5.2 KiB Raw Blame History