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>

QUICKSTART.md

@@ -0,0 +1,106 @@
+# FA Design System — Quick Start
+
+## What you've got
+
+A complete Claude Code project scaffold with:
+
+- **3 agents**: token-architect, component-builder, story-writer
+- **6 slash commands**: /create-tokens, /build-atom, /build-molecule, /sync-tokens, /status, /review-component
+- **4 memory files**: session-log, decisions-log, component-registry, token-registry
+- **2 convention docs**: token-conventions, component-conventions
+- **Living design system spec**: docs/design-system.md
+- **MCP config**: Figma remote MCP pre-configured
+- **Full React + MUI + Storybook + Style Dictionary setup**
+
+## Setup (5-10 minutes)
+
+```bash
+# 1. Extract the project
+tar -xzf fa-design-system-scaffold.tar.gz
+cd fa-project
+
+# 2. Run the bootstrap script
+chmod +x bootstrap.sh
+./bootstrap.sh
+
+# 3. Set up Figma MCP (in Claude Code)
+claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp
+# Restart Claude Code, then /mcp → authenticate with Figma
+
+# 4. Start Storybook (separate terminal)
+npm run storybook
+```
+
+## Your workflow
+
+### Step 1: Create tokens
+```
+claude
+/create-tokens I want to create the FA design system. Here are my brand colours: [paste hex values or attach reference images]. Fonts: [your font choices]. The platform serves Australian families planning funerals — warm, trustworthy, calm aesthetic.
+```
+
+### Step 2: Build atoms (one at a time)
+```
+/build-atom Button
+# Review in Storybook at http://localhost:6006
+# Provide feedback, iterate
+
+/build-atom Input
+/build-atom Typography
+/build-atom Card
+# ... etc
+```
+
+### Step 3: Build molecules
+```
+/build-molecule PriceCard
+/build-molecule FormField
+# ... etc
+```
+
+### Check status anytime
+```
+/status
+```
+
+### Review a component
+```
+/review-component Button
+```
+
+## How memory works
+
+Every agent reads these files before starting work and updates them after:
+
+| File | Purpose |
+|------|---------|
+| `docs/memory/session-log.md` | What happened last session, what's next |
+| `docs/memory/decisions-log.md` | Every design decision with rationale |
+| `docs/memory/component-registry.md` | Status of every component |
+| `docs/memory/token-registry.md` | All tokens with values and usage |
+
+This means you can close Claude Code, come back tomorrow, and the agents
+will pick up exactly where you left off.
+
+## File structure
+
+```
+fa-project/
+├── CLAUDE.md                    ← Claude Code reads this every session
+├── .claude/
+│   ├── agents/                  ← Agent definitions
+│   ├── commands/                ← Slash commands
+│   └── skills/                  ← Shared knowledge
+├── .mcp.json                    ← MCP server config
+├── docs/
+│   ├── memory/                  ← Cross-session memory
+│   ├── conventions/             ← Rules agents follow
+│   ├── reference/               ← Setup guides
+│   └── design-system.md         ← Living design spec
+├── tokens/                      ← DTCG token JSON (source of truth)
+├── style-dictionary/            ← Token build config
+├── src/
+│   ├── theme/                   ← MUI theme + generated CSS vars
+│   └── components/              ← Atoms, molecules, organisms
+└── .storybook/                  ← Storybook config with theme provider
+```