SimpleFinanceDash/.planning/phases/01-design-token-foundation/01-01-PLAN.md

---
phase: 01-design-token-foundation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - frontend/src/index.css
  - frontend/src/lib/palette.ts
  - frontend/src/lib/palette.test.ts
  - frontend/src/test-setup.ts
  - frontend/vite.config.ts
  - frontend/package.json
autonomous: true
requirements:
  - DSGN-01
  - DSGN-02
  - DSGN-05

must_haves:
  truths:
    - "All shadcn CSS variables in :root use pastel oklch values with non-zero chroma (no oklch(L 0 0) neutrals remain except --card which stays pure white)"
    - "palette.ts exports typed color objects for all 7 category types with 3 shades each (light, medium, base)"
    - "headerGradient() returns a valid CSSProperties object with a linear-gradient background"
    - "amountColorClass() returns text-success for positive income, text-warning for over-budget expenses, text-destructive for negative available"
    - "Custom --success and --warning CSS tokens exist in :root and are registered in @theme inline"
  artifacts:
    - path: "frontend/src/index.css"
      provides: "Pastel oklch CSS variables for all shadcn tokens, plus --success and --warning semantic tokens"
      contains: "--success"
    - path: "frontend/src/lib/palette.ts"
      provides: "Single source of truth for category colors with typed exports"
      exports: ["palette", "CategoryType", "CategoryShades", "headerGradient", "overviewHeaderGradient", "amountColorClass"]
    - path: "frontend/src/lib/palette.test.ts"
      provides: "Unit tests for palette exports, headerGradient, and amountColorClass"
      min_lines: 40
  key_links:
    - from: "frontend/src/index.css"
      to: "frontend/src/lib/palette.ts"
      via: "--chart-* CSS vars synced with palette base colors"
      pattern: "chart-[1-5]"
    - from: "frontend/src/lib/palette.ts"
      to: "@/lib/utils"
      via: "amountColorClass returns Tailwind utility classes that reference CSS variables"
      pattern: "text-success|text-warning|text-destructive"
---

<objective>
Establish the pastel CSS variable system and palette.ts module that all subsequent visual work depends on.

Purpose: This is the foundation layer. Every component change in Plan 02 references the tokens and palette created here. Without this, component wiring would hardcode new values instead of referencing a single source of truth.
Output: Pastel-tinted index.css, typed palette.ts with helpers, passing unit tests.
</objective>

<execution_context>
@/home/jean-luc-makiola/.claude/get-shit-done/workflows/execute-plan.md
@/home/jean-luc-makiola/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-design-token-foundation/01-CONTEXT.md
@.planning/phases/01-design-token-foundation/01-RESEARCH.md
@.planning/phases/01-design-token-foundation/01-VALIDATION.md

@frontend/src/index.css
@frontend/vite.config.ts
@frontend/package.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Install test infrastructure and set up vitest</name>
  <files>frontend/package.json, frontend/vite.config.ts, frontend/src/test-setup.ts</files>
  <action>
1. Install test dependencies:
   `cd frontend && bun add -d vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom`

2. Update `frontend/vite.config.ts` — add a `test` block inside `defineConfig`:
   ```
   test: {
     environment: 'jsdom',
     globals: true,
     setupFiles: ['./src/test-setup.ts'],
   }
   ```
   Import `/// <reference types="vitest" />` at the top of the file.

3. Create `frontend/src/test-setup.ts`:
   ```typescript
   import '@testing-library/jest-dom'
   ```

4. Verify the test runner starts: `cd frontend && bun vitest run --reporter=verbose` (should exit 0 with "no test files found" or similar).
  </action>
  <verify>
    <automated>cd /home/jean-luc-makiola/Development/projects/SimpleFinanceDash/frontend && bun vitest run --reporter=verbose 2>&1 | tail -5</automated>
  </verify>
  <done>vitest runs successfully with zero failures. test-setup.ts imports jest-dom matchers. vite.config.ts has test block with jsdom environment.</done>
</task>

<task type="auto" tdd="true">
  <name>Task 2: Replace CSS tokens with pastel oklch values and add success/warning tokens</name>
  <files>frontend/src/index.css</files>
  <behavior>
    - Manual verification: every oklch value in :root has chroma > 0 (except --card which stays oklch(1 0 0) per locked decision "cards stay pure white")
    - --success and --warning tokens exist in :root
    - --color-success and --color-warning are registered in @theme inline
    - --chart-1 through --chart-5 map to category base colors (bill, variable_expense, debt, saving, investment)
  </behavior>
  <action>
Replace ALL zero-chroma oklch values in the `:root` block of `frontend/src/index.css` with pastel-tinted equivalents. Follow these locked decisions:

**Background and surface tokens (lavender tint, hue ~290):**
- `--background: oklch(0.98 0.005 290)` — very subtle lavender tint
- `--card: oklch(1 0 0)` — KEEP pure white (cards float on tinted bg)
- `--card-foreground: oklch(0.145 0.005 290)` — near-black with slight tint
- `--popover: oklch(1 0 0)` — pure white like cards
- `--popover-foreground: oklch(0.145 0.005 290)`
- `--foreground: oklch(0.145 0.005 290)`

**Primary/accent tokens (soft lavender-blue, hue ~260-280):**
- `--primary: oklch(0.50 0.12 260)` — soft lavender-blue
- `--primary-foreground: oklch(0.99 0.005 290)`
- `--secondary: oklch(0.95 0.015 280)`
- `--secondary-foreground: oklch(0.25 0.01 280)`
- `--muted: oklch(0.95 0.010 280)`
- `--muted-foreground: oklch(0.50 0.01 280)`
- `--accent: oklch(0.94 0.020 280)`
- `--accent-foreground: oklch(0.25 0.01 280)`
- `--ring: oklch(0.65 0.08 260)` — tinted focus ring
- `--border: oklch(0.91 0.008 280)` — subtle lavender border
- `--input: oklch(0.91 0.008 280)`

**Sidebar tokens (slightly more distinct lavender):**
- `--sidebar: oklch(0.97 0.012 280)`
- `--sidebar-foreground: oklch(0.20 0.01 280)`
- `--sidebar-primary: oklch(0.50 0.12 260)`
- `--sidebar-primary-foreground: oklch(0.99 0.005 290)`
- `--sidebar-accent: oklch(0.93 0.020 280)`
- `--sidebar-accent-foreground: oklch(0.25 0.01 280)`
- `--sidebar-border: oklch(0.90 0.010 280)`
- `--sidebar-ring: oklch(0.65 0.08 260)`

**Chart tokens (mapped to category base colors — synced with palette.ts):**
- `--chart-1: oklch(0.76 0.12 250)` — bill (blue)
- `--chart-2: oklch(0.80 0.14 85)` — variable_expense (amber)
- `--chart-3: oklch(0.76 0.13 15)` — debt (rose)
- `--chart-4: oklch(0.75 0.13 280)` — saving (violet)
- `--chart-5: oklch(0.76 0.12 320)` — investment (pink)

**NEW semantic tokens — add to :root block:**
- `--success: oklch(0.55 0.15 145)` — green for positive amounts
- `--success-foreground: oklch(0.99 0 0)`
- `--warning: oklch(0.70 0.14 75)` — amber for over-budget
- `--warning-foreground: oklch(0.99 0 0)`

**NEW @theme inline additions — add these lines:**
```css
--color-success: var(--success);
--color-success-foreground: var(--success-foreground);
--color-warning: var(--warning);
--color-warning-foreground: var(--warning-foreground);
```

Do NOT modify the `.dark` block (dark mode is out of scope). Do NOT touch the `@layer base` block.
  </action>
  <verify>
    <automated>cd /home/jean-luc-makiola/Development/projects/SimpleFinanceDash && grep -c "oklch.*0 0)" frontend/src/index.css | head -1</automated>
  </verify>
  <done>The :root block has zero remaining zero-chroma neutral tokens (except --card and --popover which are intentionally pure white). --success and --warning tokens exist in :root and are registered in @theme inline. All chart tokens map to category base colors. The .dark block is unchanged.</done>
</task>

<task type="auto" tdd="true">
  <name>Task 3: Create palette.ts and palette.test.ts</name>
  <files>frontend/src/lib/palette.ts, frontend/src/lib/palette.test.ts</files>
  <behavior>
    - palette exports all 7 CategoryType values: income, bill, variable_expense, debt, saving, investment, carryover
    - Each category has 3 shades: light, medium, base — all non-empty oklch strings
    - headerGradient('bill') returns { background: 'linear-gradient(to right, ...)' }
    - overviewHeaderGradient() returns a multi-stop gradient for FinancialOverview
    - amountColorClass({ type: 'income', actual: 100, budgeted: 0, isIncome: true }) returns 'text-success'
    - amountColorClass({ type: 'income', actual: 0, budgeted: 0, isIncome: true }) returns ''
    - amountColorClass({ type: 'bill', actual: 200, budgeted: 100 }) returns 'text-warning'
    - amountColorClass({ type: 'bill', actual: 100, budgeted: 100 }) returns '' (exactly on budget = normal)
    - amountColorClass({ type: 'bill', actual: 50, budgeted: 100 }) returns '' (under budget = normal)
    - amountColorClass({ type: 'bill', actual: 0, budgeted: 0, isAvailable: true }) returns ''
    - amountColorClass({ type: 'bill', actual: 500, budgeted: 0, isAvailable: true }) returns 'text-success'
    - amountColorClass({ type: 'bill', actual: -100, budgeted: 0, isAvailable: true }) returns 'text-destructive'
  </behavior>
  <action>
**Write tests first (RED):**

Create `frontend/src/lib/palette.test.ts` with tests covering all behaviors listed above. Group into describe blocks: "palette exports", "headerGradient", "overviewHeaderGradient", "amountColorClass".

Run tests — they must FAIL (module not found).

**Write implementation (GREEN):**

Create `frontend/src/lib/palette.ts` with these exports:

1. `CategoryType` — union type of all 7 category strings
2. `CategoryShades` — interface with `light`, `medium`, `base` string fields
3. `palette` — `Record<CategoryType, CategoryShades>` with oklch values per locked decisions:
   - income: hue 145 (green), light L=0.96 C=0.04, medium L=0.88 C=0.08, base L=0.76 C=0.14
   - bill: hue 250 (blue), light L=0.96 C=0.03, medium L=0.88 C=0.07, base L=0.76 C=0.12
   - variable_expense: hue 85 (amber), light L=0.97 C=0.04, medium L=0.90 C=0.08, base L=0.80 C=0.14
   - debt: hue 15 (rose), light L=0.96 C=0.04, medium L=0.88 C=0.08, base L=0.76 C=0.13
   - saving: hue 280 (violet), light L=0.95 C=0.04, medium L=0.87 C=0.08, base L=0.75 C=0.13
   - investment: hue 320 (pink), light L=0.96 C=0.04, medium L=0.88 C=0.07, base L=0.76 C=0.12
   - carryover: hue 210 (sky), light L=0.96 C=0.03, medium L=0.88 C=0.06, base L=0.76 C=0.11

4. `headerGradient(type: CategoryType): React.CSSProperties` — returns `{ background: 'linear-gradient(to right, ${light}, ${medium})' }`

5. `overviewHeaderGradient(): React.CSSProperties` — returns a multi-stop gradient using carryover.light, saving.light, and income.light (sky via lavender to green) for the FinancialOverview header

6. `amountColorClass(opts)` — implements the locked amount coloring rules:
   - `isAvailable` or `isIncome` path: positive → 'text-success', negative → 'text-destructive', zero → ''
   - Expense path: actual > budgeted → 'text-warning', else → ''

**IMPORTANT:** The base colors for bill, variable_expense, debt, saving, investment MUST match the --chart-1 through --chart-5 values set in Task 2's index.css. These are the same oklch strings.

Run tests — they must PASS.
  </action>
  <verify>
    <automated>cd /home/jean-luc-makiola/Development/projects/SimpleFinanceDash/frontend && bun vitest run src/lib/palette.test.ts --reporter=verbose</automated>
  </verify>
  <done>All palette.test.ts tests pass. palette.ts exports all 7 categories with 3 shades each. headerGradient returns valid gradient CSSProperties. amountColorClass correctly returns text-success/text-warning/text-destructive/empty string per the locked rules.</done>
</task>

</tasks>

<verification>
1. `cd frontend && bun vitest run --reporter=verbose` — all tests pass
2. `grep -c "oklch.*0 0)" frontend/src/index.css` — returns a small number (only --card and --popover intentionally white)
3. `grep "success\|warning" frontend/src/index.css` — shows the new semantic tokens
4. palette.ts exports are importable: `cd frontend && bun -e "import { palette } from './src/lib/palette'; console.log(Object.keys(palette).length)"` — prints 7
</verification>

<success_criteria>
- Zero zero-chroma neutrals remain in :root (except intentional pure white on --card/--popover)
- palette.ts is the single source of truth for 7 category types x 3 shades
- headerGradient and amountColorClass helpers work correctly per unit tests
- --success and --warning CSS variables are usable as Tailwind utilities (text-success, text-warning)
- --chart-1 through --chart-5 values match palette.ts base colors
- vitest runs with all tests green
</success_criteria>

<output>
After completion, create `.planning/phases/01-design-token-foundation/01-01-SUMMARY.md`
</output>