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>

docs/reference/mcp-setup.md

@@ -0,0 +1,127 @@
+# MCP server setup
+
+## 1. Figma remote MCP
+
+Used for: Reading FA 1.0 designs, extracting component context, getting design
+properties for reference when building components.
+
+### Setup
+
+```bash
+# Add the Figma remote MCP to Claude Code
+claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp
+
+# Restart Claude Code, then authenticate:
+# Run /mcp → select figma-remote-mcp → Authenticate
+# This opens a browser for Figma OAuth
+```
+
+### Verify connection
+
+```bash
+# In Claude Code:
+/mcp
+# Should show: figma-remote-mcp (connected)
+```
+
+### Usage
+
+The Figma MCP is link-based. To use it:
+1. Open your FA 1.0 Figma file
+2. Select a frame or component
+3. Copy the link (right-click → Copy link to selection, or copy from browser URL bar)
+4. Paste the link in your Claude Code prompt
+
+Example prompts:
+- "Get the design context for this button: [figma-link]"
+- "What colours and spacing does this card use? [figma-link]"
+- "Extract the component structure of this form: [figma-link]"
+
+### Rate limits
+
+With a Figma Professional plan, you get per-minute rate limits (Tier 1 REST API
+equivalent). This is sufficient for component-by-component extraction.
+
+---
+
+## 2. Storybook MCP
+
+Used for: Querying the component library during composition — finding available
+components, checking props, getting usage examples.
+
+### Prerequisites
+
+Storybook must be running locally before the MCP can connect.
+
+```bash
+# Start Storybook
+npm run storybook
+# This runs on http://localhost:6006 by default
+```
+
+### Setup — Standalone Storybook MCP
+
+```bash
+# Add the Storybook MCP server to Claude Code
+claude mcp add storybook --transport http http://localhost:6006/mcp
+```
+
+Or add to `.mcp.json` in the project root:
+```json
+{
+  "mcpServers": {
+    "storybook": {
+      "url": "http://localhost:6006/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+**Note:** Storybook must be running before the MCP server can connect.
+
+### Verify connection
+
+```bash
+# In Claude Code (with Storybook running):
+/mcp
+# Should show: storybook (connected)
+```
+
+### Usage
+
+The Storybook MCP exposes tools for querying your component library:
+- List all available components
+- Get component props and their types
+- Find components by keyword
+- Get usage examples from stories
+
+This is primarily used by the layout-composer agent (for later phases) to
+discover and correctly use components when building page layouts.
+
+---
+
+## 3. Penpot MCP (for later — layout phase)
+
+Setup instructions will be added when you reach the layout composition phase.
+The Penpot MCP requires either the official Penpot MCP plugin running locally,
+or the Docker-based server alongside a self-hosted Penpot instance.
+
+---
+
+## Troubleshooting
+
+### Figma MCP not connecting
+- Restart Claude Code completely (MCP connections initialise at startup)
+- Re-authenticate: `/mcp` → select figma-remote-mcp → Authenticate
+- Check you're on a Figma Professional plan (Starter has 6 calls/month)
+
+### Storybook MCP not connecting
+- Ensure Storybook is running (`npm run storybook`)
+- Check the port: default is 6006, but it may use 6007+ if 6006 is occupied
+- Restart Claude Code after starting Storybook
+
+### General MCP issues
+- Run `/mcp` to see status of all servers
+- Check for error messages in the MCP status output
+- Try removing and re-adding: `claude mcp remove <name>` then re-add