# Workflow Plan — Figma + Code + Storybook

## Problem

We have three tools — Figma (design), code (React/Tailwind/TypeScript), and Storybook (component dev/docs/testing) — plus MCP servers for both Figma and Storybook. We need a clear process for how these connect as we build components, and what tooling/skills are worth adding to streamline things.

---

## Two Entry Points, One Loop

Components can start from either direction — the key is that both converge on the same verification and linking steps.

### Entry A: Design-First (Figma → React)

Richie has designed a component in Figma. We implement it in code.

1. **Inspect** — `get_design_context` on the Figma node returns reference code, a screenshot, and metadata.
2. **Extract tokens** — `get_variable_defs` pulls colours, spacing, typography values. Cross-check against `tokens.css` to confirm tokens exist or flag gaps.
3. **Check existing components** — Storybook MCP `get-documentation` lists what we've already built. Reuse before rebuilding.
4. **Build** — React component with TypeScript props, Tailwind utilities via `cn()`, tokens from `tokens.css`.
5. **Story** — Write stories using Storybook MCP `get-storybook-story-instructions` to match current conventions. Cover default, variants, edge cases.
6. **Test** — Storybook MCP `run-story-tests` for rendering + a11y. Fix violations before moving on.
7. **Visual verify** — `get_screenshot` from Figma vs Storybook preview. Compare side-by-side.
8. **Link** — `add_code_connect_map` to link the Figma component to the React component.
9. **Embed** — Add `addon-designs` parameter to the story pointing back to the Figma source.

### Entry B: Code-First (React → Figma)

Claude builds a component from a description or reference. We push it to Figma for Richie to review.

1. **Build** — React component in code, using design tokens from `tokens.css`.
2. **Story** — Write stories, verify in Storybook (same as steps 5-6 above).
3. **Push to Figma** — `use_figma` to create the component/frame/variants. The claude2figma skills enforce token binding here — no hardcoded values.
4. **Verify** — `get_screenshot` to confirm it landed correctly.
5. **Link** — `add_code_connect_map` to bridge it back.
6. **Embed** — Add `addon-designs` parameter to the story.

We used this flow when creating the typography specimen frame.

### The Shared End State

Regardless of entry point, every finished component has:
- A React implementation with typed props and Tailwind styling
- Storybook stories with autodocs, variants, and a11y coverage
- A Figma representation using bound tokens/variables
- A Code Connect link bridging the two
- An `addon-designs` embed in its story for side-by-side comparison

---

## Where Storybook Fits in Both Directions

Storybook isn't just for docs — with its MCP server it becomes the **verification layer** in both directions:

| Capability | MCP Tool | When to use |
|---|---|---|
| List existing components | `list-all-documentation` | Before building anything — check what exists |
| Get component API | `get-documentation` | When composing or extending existing components |
| Story conventions | `get-storybook-story-instructions` | When writing new stories — ensures consistency |
| Visual preview | `preview-stories` | After building — visual confirmation in-context |
| Test + a11y | `run-story-tests` | After every component build — catches violations early |

### Addon: `@storybook/addon-designs`

Embeds Figma frames directly in the Storybook addon panel. Each story can link to its Figma source:

```tsx
parameters: {
  design: {
    type: 'figma',
    url: 'https://www.figma.com/design/mrabO6AtxN3ektGiTk0I9c/ResearchInsights?node-id=...',
  },
},
```

This creates a permanent link between implementation and design intent — developers see the spec alongside the rendered component without switching tools.

Both addons are installed and registered in `.storybook/main.ts`.

---

## Code Connect — The Bridge Layer

Code Connect is the most important piece we haven't set up yet. It links Figma components to their React implementations, so:

- `get_design_context` returns our actual component code instead of generic markup
- Designers see real implementation details in Figma's Dev Mode
- The mapping grows as we build — each new component strengthens the bridge

**Setup:**
1. As we build each component, call `add_code_connect_map` with label "React"
2. For existing components, use `get_code_connect_suggestions` to get AI-suggested mappings
3. Periodically run `get_code_connect_map` to audit coverage

---

## Skills and Tooling to Add

### Adopt now

| Skill | What it does | Why |
|---|---|---|
| **claude2figma** (4 skills) | Preflight reads all tokens/styles/components before writing; Component Rules enforces library instance usage; Style Binding binds colours/text/spacing to variables with QA; Reference Interpreter parses design references into structured briefs | Directly solves token fidelity when writing to Figma. Prevents hardcoded values. |
| **Built-in /simplify** | Three parallel review agents check reuse, quality, efficiency | Already available. Run after building each component. |
| **Built-in /review** | Code correctness review | Already available. Run before committing. |
| **Built-in /verify** | Launches the app and confirms the change works visually | Already available. Use for visual confirmation. |

### Evaluate

| Skill | What it does | Verdict |
|---|---|---|
| **Storybook docs skill** (thebushidocollective) | Generates comprehensive Storybook docs with MDX, autodocs, JSDoc | Test whether it adds value beyond Storybook MCP's built-in `get-storybook-story-instructions`. May be redundant. |
| **A11y audit skill** | WCAG compliance, screen reader support, keyboard navigation | The Storybook a11y addon + `run-story-tests` already covers per-component checks. An audit skill would add value for periodic full-system sweeps. |

### Skip

| Skill | Why skip |
|---|---|
| **frontend-design** (Anthropic) | We're implementing an existing NSW design system, not making creative aesthetic choices |
| **awesome-design-md** | We have our own design language from Figma |
| **React specialist subagent** | CLAUDE.md already covers these conventions |

---

## The Component Build Checklist

Regardless of entry point, every component should pass through these gates:

```
[ ] Design reference exists (Figma frame OR code-first build)
[ ] Tokens checked (get_variable_defs vs tokens.css — flag gaps)
[ ] Existing components checked (Storybook MCP list-all-documentation)
[ ] React component built (TypeScript, Tailwind, cn(), forwardRef)
[ ] Stories written (default + variants + edge cases + autodocs)
[ ] Tests pass (Storybook MCP run-story-tests, including a11y)
[ ] Visual verified (Figma screenshot vs Storybook side-by-side)
[ ] Figma representation exists (designed by Richie OR pushed via use_figma)
[ ] Code Connect linked (add_code_connect_map, label: React)
[ ] Figma embed in story (addon-designs parameter)
[ ] /simplify run
```

---

## Decisions Made

- **claude2figma skills** — Installed (4 skills in `.claude/skills/`)
- **Storybook addons** — `addon-designs` + `addon-mcp` installed and registered
- **Code Connect** — Link as we build, regardless of entry point
- **Build order** — Start with primitives, work up to composites then layouts