ADS3-Design-System/plans/workflow.md

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:

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