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.

---

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:

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