Initial commit: FA 2.0 Design System foundation

Token pipeline (Style Dictionary v4, DTCG format):
- Primitive tokens: colour palettes (brand, sage, neutral, feedback),
  typography (3 font families, 21-variant type scale), spacing (4px grid),
  border radius, shadows, opacity
- Semantic tokens: text, surface, border, interactive, feedback colours;
  typography roles; layout spacing
- Component tokens: Button (4 sizes), Input (2 sizes)
- Generated outputs: CSS custom properties, JS ES6 module, flat JSON

Atoms (3 components):
- Button: contained/soft/outlined/text × primary/secondary, 4 sizes,
  loading state, underline for text variant
- Typography: 21 variants across display/heading/body/label/caption/overline,
  maxLines truncation
- Input: external label, helper text, error/success validation,
  start/end icons, required indicator, 2 sizes, multiline support

Infrastructure:
- MUI v5 theme with full token mapping
- Storybook 8 with autodocs
- Claude Code agents and skills for token/component workflows
- Design system documentation and cross-session memory

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,80 @@
+# FA 2.0 Design System
+
+## Project overview
+
+Rebuilding the Funeral Arranger (funeralarranger.com.au) design system using a
+code-first approach. Parsons (H.Parsons Funeral Directors) is the client. FA is
+an Australian funeral planning platform — the design language must be warm,
+professional, trustworthy, and calm. Users are often in distress.
+
+## Tech stack
+
+- React 18 + TypeScript
+- Material UI (MUI) v5
+- Storybook 8+ with autodocs
+- Style Dictionary for token transformation
+- W3C DTCG token format (2025.10 stable spec)
+- Chromatic for Storybook hosting (later)
+
+## Architecture
+
+**Source of truth:** Token JSON files in `tokens/` (DTCG format)
+**Flow:** Token JSON → Style Dictionary → MUI theme + CSS vars → React components → Storybook
+
+### Token tiers
+1. **Primitives** (`tokens/primitives/`): Raw values — hex, px, font names, scales
+2. **Semantic** (`tokens/semantic/`): Design intent — `color.text.primary`, `color.surface.default`
+3. **Component** (`tokens/component/`): Per-component — `button.background.default`
+
+### Component tiers (atomic design)
+1. **Atoms** (`src/components/atoms/`): Button, Input, Typography, Badge, Icon, Avatar, Divider, Chip, Card, Link
+2. **Molecules** (`src/components/molecules/`): SearchBar, PriceCard, ServiceOption, FormField
+3. **Organisms** (`src/components/organisms/`): ServiceSelector, PricingTable, ArrangementForm, Navigation
+
+## Critical rules
+
+1. **Every component MUST consume the MUI theme** — never hardcode colours, spacing, typography, or shadows
+2. **Every token MUST have a `$description`** — this is how agents maintain context about design intent
+3. **Always read docs/design-system.md** before creating or modifying anything
+4. **Always check docs/memory/** before starting work — these files contain decisions and state from previous sessions
+5. **Always update docs/memory/** after completing work — log what was done, decisions made, and open questions
+6. **Run `npm run build:tokens`** after any token JSON change
+7. **Verify in Storybook** before marking any component done
+
+## Memory system
+
+This project uses structured markdown files for cross-session memory.
+
+**Before starting any work, read these files:**
+- `docs/memory/decisions-log.md` — All design decisions with rationale
+- `docs/memory/component-registry.md` — Status of every component (planned/in-progress/done)
+- `docs/memory/token-registry.md` — All tokens with their current values and usage notes
+- `docs/memory/session-log.md` — What was done in previous sessions, what's next
+
+**After completing work, update:**
+- The relevant memory files with what changed
+- `docs/memory/session-log.md` with a summary of what was accomplished and next steps
+
+## MCP servers
+
+- **Figma remote MCP** (`figma-remote-mcp`): Read FA 1.0 designs, extract design context
+- **Storybook MCP** (`storybook`): Query component library for available components and props
+
+Setup instructions in `docs/reference/mcp-setup.md`.
+
+## File conventions
+
+- Component folders: PascalCase (`Button/`, `PriceCard/`)
+- Token files: camelCase (`colours.json`, `typography.json`)
+- Each component folder contains: `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
+- CSS custom properties prefix: `--fa-` (e.g., `--fa-color-brand-primary`)
+- MUI theme paths: follow MUI conventions (`palette.primary.main`)
+
+## Naming conventions for tokens
+
+See `docs/conventions/token-conventions.md` for the full specification.
+
+Quick reference:
+- Primitives: `color.blue.500`, `spacing.4`, `fontSize.base`
+- Semantic: `color.text.primary`, `color.surface.default`, `color.interactive.default`
+- Component: `button.background.default`, `button.background.hover`