# 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
```