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

---

## Workflow: Code-First with Figma Reference

Components are built in code and verified in Storybook. Figma serves as a **visual reference** — Richie may provide Figma links or screenshots to guide design intent, but we don't create or maintain Figma representations of each component as part of the build process. Figma design can be added later if needed.

### Build Steps

1. **Reference** — Richie provides design intent: a Figma link, screenshot, description, or existing component to match. Use `get_design_context` / `get_screenshot` to inspect Figma references when provided.
2. **Check tokens** — Cross-check the reference against `tokens.css`. Flag any gaps (missing colours, spacing, etc.) before building.
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 covering default, variants, and edge cases. Use `tags: ['autodocs']`.
6. **Test** — Storybook MCP `run-story-tests` for rendering + a11y. Fix violations before moving on.
7. **Visual verify** — Playwright screenshots of Storybook stories to confirm rendering.
8. **Embed** — If a Figma reference exists, add `addon-designs` parameter to the story for side-by-side comparison.

### The Finished State

Every completed component has:
- A React implementation with typed props and Tailwind styling
- Storybook stories with autodocs, variants, and a11y coverage
- An `addon-designs` embed in its story if a Figma reference exists

---

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

---

## Skills and Tooling

### 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 provided (Figma link, screenshot, or description)
[ ] Tokens checked (reference 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 (Playwright screenshots of Storybook)
[ ] Figma embed in story (addon-designs parameter, if reference exists)
```

---

## Decisions Made

- **Code-first workflow** — Build in React + Storybook, use Figma as visual reference only (not as a build target)
- **claude2figma skills** — Installed but deferred; will use when/if pushing designs to Figma later
- **Storybook addons** — `addon-designs` + `addon-mcp` installed and registered
- **Code Connect** — Deferred (requires Org/Enterprise Figma plan)
- **Build order** — Start with primitives, work up to composites then layouts