Ready2Blob/.planning/phases/08-theme-foundation/08-01-PLAN.md

---
phase: 08-theme-foundation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - src/index.css
  - index.html
  - src/components/ui/ThemeToggle.tsx
  - src/components/ui/ThemeToggle.test.tsx
  - src/App.tsx
autonomous: true
requirements:
  - THEME-01
  - THEME-02

must_haves:
  truths:
    - "Tailwind utility classes bg-surface, text-on-surface, bg-primary, text-on-primary, border-outline etc. are available and resolve to correct hex values"
    - "Adding .dark class to html element switches all token values to dark palette"
    - "ThemeToggle renders three options: Light, Dark, System"
    - "Clicking a theme option applies the correct class to document.documentElement and persists to localStorage"
    - "On hard reload with r2b-theme=dark in localStorage, the .dark class is present before React mounts (no flash)"
  artifacts:
    - path: "src/index.css"
      provides: "MD3 color token definitions (light + dark) and @theme mapping"
      contains: "@theme"
    - path: "index.html"
      provides: "Inline blocking script for flash prevention"
      contains: "r2b-theme"
    - path: "src/components/ui/ThemeToggle.tsx"
      provides: "Segmented theme toggle component"
      exports: ["ThemeToggle"]
    - path: "src/components/ui/ThemeToggle.test.tsx"
      provides: "Unit tests for ThemeToggle behavior"
      contains: "describe"
    - path: "src/App.tsx"
      provides: "ThemeToggle wired into header, bg-surface applied to shell"
      contains: "ThemeToggle"
  key_links:
    - from: "src/index.css"
      to: "src/components/ui/ThemeToggle.tsx"
      via: ".dark class on html toggles CSS variable cascade"
      pattern: "classList\\.toggle.*dark"
    - from: "index.html"
      to: "localStorage"
      via: "inline script reads r2b-theme before paint"
      pattern: "localStorage\\.getItem.*r2b-theme"
    - from: "src/App.tsx"
      to: "src/components/ui/ThemeToggle.tsx"
      via: "import and render in header"
      pattern: "import.*ThemeToggle"
---

<objective>
Build the MD3 color token system, dark mode infrastructure, and ThemeToggle component.

Purpose: Establish the CSS custom property foundation that all components will reference instead of hardcoded Tailwind colors. This is the infrastructure layer that Plan 02 (migration) and Phases 9-11 depend on.
Output: Working token system with dark mode toggle, flash prevention, and ThemeToggle component with unit tests.
</objective>

<execution_context>
@C:/Users/SebastienQUEROL/.claude/get-shit-done/workflows/execute-plan.md
@C:/Users/SebastienQUEROL/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/08-theme-foundation/08-CONTEXT.md
@.planning/phases/08-theme-foundation/08-RESEARCH.md

<interfaces>
<!-- Current src/index.css is just: @import "tailwindcss"; -->
<!-- Current index.html has no inline scripts -->

From src/App.tsx (current structure):
```tsx
import { useWizard } from './store/context';
import { WizardProvider } from './store/context';
import { StepIndicator } from './components/wizard/StepIndicator';
// ... step imports

function WizardShell() {
  const { state } = useWizard();
  // ...
  return (
    <div className="min-h-screen bg-gray-50 flex flex-col items-center py-12 px-4">
      <div className="w-full max-w-2xl">
        <h1 className="text-3xl font-bold text-gray-900 mb-8 text-center">Ready2Blob</h1>
        <StepIndicator />
        <div className="mt-8">{CurrentStep}</div>
      </div>
    </div>
  );
}
```
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Define MD3 color tokens and flash prevention script</name>
  <files>src/index.css, index.html</files>
  <action>
**src/index.css** — Replace the single `@import "tailwindcss"` line with the complete token system. Structure (in this exact order):

1. `@import "tailwindcss";`
2. `@custom-variant dark (&:where(.dark, .dark *));` — immediately after import, before any @layer or @theme
3. `@layer base` block with `:root` (light values) and `.dark` (dark values) for all tokens:
   - `--r2b-primary`: light #4338CA, dark #A5B4FC
   - `--r2b-on-primary`: light #FFFFFF, dark #1E1B4B
   - `--r2b-surface`: light #F9FAFB, dark #111827
   - `--r2b-on-surface`: light #111827, dark #F9FAFB
   - `--r2b-surface-variant`: light #1F2937, dark #0F172A (code blocks)
   - `--r2b-on-surface-variant`: light #F3F4F6, dark #E5E7EB
   - `--r2b-surface-container`: light #FFFFFF, dark #1F2937 (cards/forms)
   - `--r2b-on-surface-container`: light #374151, dark #D1D5DB
   - `--r2b-outline`: light #D1D5DB, dark #4B5563
   - `--r2b-error`: light #EF4444, dark #FCA5A5
   - `--r2b-on-error`: light #FFFFFF, dark #7F1D1D
   - Also add warning/success tokens per research recommendation:
     - `--r2b-success`: light #15803D (green-700), dark #86EFAC (green-300)
     - `--r2b-on-success`: light #F0FDF4 (green-50), dark #14532D (green-900)
     - `--r2b-warning`: light #D97706 (amber-600), dark #FCD34D (amber-300)
     - `--r2b-on-warning`: light #FFFBEB (amber-50), dark #78350F (amber-900)
   Also add `body` transition in `@layer base`: `transition: background-color 200ms ease, color 200ms ease, border-color 200ms ease` with `@media (prefers-reduced-motion: reduce)` wrapper that sets `transition: none`.
4. `@theme` block mapping each `--color-*` to `var(--r2b-*)` for all 15 tokens (the 11 core + warning, on-warning, success, on-success).

**index.html** — Add inline blocking script inside `<head>`, BEFORE any stylesheet or script tags. The script:
1. Reads `localStorage.getItem('r2b-theme')`
2. If `'dark'` -> effective = dark. If `'light'` -> effective = light. Otherwise -> check `window.matchMedia('(prefers-color-scheme: dark)').matches`
3. If effective is dark, add `.dark` to `document.documentElement.classList`
4. Wrap in try/catch for private browsing mode safety

Use vanilla JS (no arrow functions) for maximum browser compat in the inline script. Use the exact pattern from 08-RESEARCH.md Pattern 2.
  </action>
  <verify>
    <automated>cd C:/Users/SebastienQUEROL/Documents/projets/Ready2Blob && npx vite build 2>&1 | tail -5</automated>
  </verify>
  <done>src/index.css contains @custom-variant, @layer base with :root and .dark blocks (15 token pairs), @theme mapping all tokens. index.html has inline blocking script reading r2b-theme from localStorage. Vite build succeeds with no errors.</done>
</task>

<task type="auto" tdd="true">
  <name>Task 2: Create ThemeToggle component with tests and wire into App.tsx</name>
  <files>src/components/ui/ThemeToggle.tsx, src/components/ui/ThemeToggle.test.tsx, src/App.tsx</files>
  <behavior>
    - ThemeToggle renders three buttons: Light, Dark, System
    - Each button has role="button" and aria-pressed reflecting current selection
    - The component group has aria-label="Theme"
    - Default selection is "system" when localStorage is empty
    - Clicking "Dark" adds .dark class to document.documentElement
    - Clicking "Light" removes .dark class from document.documentElement
    - Clicking any option writes the value to localStorage key "r2b-theme"
    - Active button uses bg-primary text-on-primary classes
    - Inactive buttons use bg-surface-container text-on-surface-container classes
  </behavior>
  <action>
**ThemeToggle.test.tsx** (RED first):
Write tests using Vitest + jsdom (add `// @vitest-environment jsdom` pragma). Test:
1. Renders three buttons with text containing "Light", "Dark", "System"
2. Default state is "System" (aria-pressed="true" on System button) when localStorage is empty
3. Clicking "Dark" -> `document.documentElement.classList.contains('dark')` is true
4. Clicking "Light" -> `document.documentElement.classList.contains('dark')` is false
5. Clicking "Dark" -> `localStorage.getItem('r2b-theme')` === `'dark'`
6. Active button has aria-pressed="true", others have aria-pressed="false"

Run tests — they must FAIL (RED).

**ThemeToggle.tsx** (GREEN):
Create the component following 08-RESEARCH.md Pattern 3:
- Type `ThemeValue = 'light' | 'dark' | 'system'`
- `STORAGE_KEY = 'r2b-theme'`
- `getStored()` reads from localStorage, returns ThemeValue (default 'system')
- `applyTheme(value)` toggles `.dark` on `document.documentElement` and writes to localStorage
- `useState<ThemeValue>(getStored)` for lazy init
- Render as a segmented control: `<div role="group" aria-label="Theme">` with three buttons
- Each button: `type="button"`, `aria-pressed={theme === v}`, `onClick={() => select(v)}`
- Active state: `bg-primary text-on-primary font-medium`
- Inactive state: `bg-surface-container text-on-surface-container hover:bg-surface`
- Icons: Sun for Light, Moon for Dark, Monitor for System (use Unicode or simple SVG inline icons)
- Outer div: `flex rounded-md border border-outline overflow-hidden text-sm`

Run tests — they must PASS (GREEN).

**App.tsx** updates:
1. Add `import { ThemeToggle } from './components/ui/ThemeToggle';`
2. Change the header from centered h1 to a flex row: `<div className="flex items-center justify-between mb-8">`
3. h1 keeps `text-3xl font-bold` but change `text-gray-900` to `text-on-surface`, remove `text-center`
4. Add `<ThemeToggle />` as second child in the flex row
5. Change outer div `bg-gray-50` to `bg-surface`
6. Change h1 `text-gray-900` to `text-on-surface`

Run full test suite to confirm no regressions.
  </action>
  <verify>
    <automated>cd C:/Users/SebastienQUEROL/Documents/projets/Ready2Blob && npm test 2>&1 | tail -20</automated>
  </verify>
  <done>ThemeToggle.test.tsx has 6+ passing tests. ThemeToggle renders segmented control with Light/Dark/System. App.tsx header shows title left and ThemeToggle right. All existing tests still pass. App outer div uses bg-surface, h1 uses text-on-surface.</done>
</task>

</tasks>

<verification>
1. `npx vite build` completes without errors
2. `npm test` — all tests pass (existing + new ThemeToggle tests)
3. `grep -c "@theme" src/index.css` returns 1 (theme block exists)
4. `grep -c "r2b-theme" index.html` returns at least 1 (inline script present)
5. `grep "ThemeToggle" src/App.tsx` confirms component is wired in
</verification>

<success_criteria>
- Token system produces working Tailwind utility classes: bg-surface, text-on-surface, bg-primary, etc.
- Dark mode toggle works: clicking Dark applies .dark class, Light removes it, System checks OS preference
- Flash prevention: inline script in index.html reads localStorage before CSS paints
- ThemeToggle has passing unit tests covering all three modes and DOM class toggling
- No regression in existing test suite
</success_criteria>

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