Design Workflow — v3 (Compiler-Driven)

Compiler-driven, recipe-accelerated workflow for designers using Claude Code to design in Figma. Powered by Figma MCP transport (console or official). See references/transport-adapter.md. Conversation in the user's language. All generated artifacts (KB, CSpecs, guides, learnings, recipes, scene graphs) in English only.

Philosophy

1. Compiler-driven — Claude produces a scene graph JSON; the compiler enforces all Figma API rules
2. Recipe-accelerated — Proven layouts are captured as parameterized templates and reused
3. DS-native — Every visual element uses design system tokens and components, never hardcoded
4. CSpec-first — Structured YAML specs that translate directly to scene graphs
5. Iterative — Make, fix, learn, ship
6. Minimal context — Only load what is needed for the current action (no bloated reads)

Knowledge Base Location

The knowledge base is project-specific. Resolve its path in this order:

1. If ./bridge-ds/knowledge-base/registries/ exists and contains JSON files -> use ./bridge-ds/knowledge-base/
2. Else if ./.claude/skills/design-workflow/references/knowledge-base/registries/ exists and contains JSON files -> use that path
3. Else -> knowledge base not found. Suggest running setup to extract the DS.

The specs/ directory is always at ./specs/ (project root), regardless of KB location. The learnings.json is always inside the knowledge base directory. The recipes/ directory is always inside the knowledge base directory.

Commands

Action Router

Detect intent from user input and read the action file BEFORE executing:

Context Loading Rules (CRITICAL)

Load MINIMAL context per action. Only these references are needed:

NEVER load figma-api-rules.md. The compiler enforces all 26 rules. Claude's job is to produce valid scene graph JSON, not write raw Figma Plugin API code.

Full Workflow

setup (first time only)
  -> Extract DS via Figma MCP transport
  -> Build knowledge base (registries + guides + recipes index)
  |
make <description>
  |
  +-- Phase A: Context (load registry index, learnings, recipes)
  +-- Phase B: Recipe Match (score against index)
  +-- Phase C: CSpec (generate YAML, apply learnings, user validates)
  +-- Phase D: Compile + Execute (JSON scene graph -> compiler -> Figma)
  +-- Phase E: Present (screenshot, report, offer next step)
  |
  +-- Iteration loop:
  |     User describes changes -> modify scene graph -> recompile -> re-execute
  |     User says "I adjusted in Figma" -> fix flow
  |     User says "done" / "ship it" -> done flow
  |
fix
  |
  +-- Re-read Figma state
  +-- Diff snapshot vs current
  +-- Classify: LEARNING (DS token) vs FLAG (hardcoded)
  +-- Save learnings, patch recipes
  +-- Offer: continue or done
  |
done
  |
  +-- Auto-fix if changes detected
  +-- Archive spec
  +-- Recipe extraction (if eligible)
  +-- Update history

Two Modes

Component mode

Design system components (Button, Card, Modal...):

make {component} -> fix (optional) -> done

CSpec uses component-cspec.yaml template. Includes: variants, props API, tokens.

Screen mode

Full interfaces (dashboard, settings, onboarding...):

make {screen}
  -> if new DS components needed:
      make {component} -> done -> back to screen
  -> fix (optional) -> done

CSpec uses screen-cspec.yaml template. Includes: layout tree, sections, DS components used.

The make action auto-detects the mode from context, or asks the user.

Project Structure

specs/
  active/          <- Current work (0-1 CSpecs + snapshots)
  backlog/         <- Queued specs
  shipped/         <- Completed & archived
  dropped/         <- Abandoned with learnings
  history.log      <- One-line per design shipped

knowledge-base/
  registries/      <- components.json, variables.json, text-styles.json, icons.json, ...
  guides/          <- tokens/, components/, patterns/, assets/
  recipes/         <- _index.json + individual recipe JSON files
  learnings.json   <- Accumulated design preferences

Status Logic (inline)

Detect state by checking:

1. Does the knowledge base exist? (registries/ has JSON files)
2. Does specs/active/ contain a CSpec?
3. Has a Figma design been generated for it? (snapshot file exists)

Quality Gates

Full definitions: references/quality-gates.md (read before any phase transition).

Non-Negotiable Rules

• ALWAYS read the action file BEFORE executing
• ALWAYS read compiler-reference.md before producing any scene graph JSON
• ALWAYS read transport-adapter.md before any MCP tool call
• ALWAYS wait for user confirmation before compiling and executing in Figma
• NEVER load figma-api-rules.md — the compiler handles all Figma API rules
• NEVER write raw Plugin API scripts manually — always go through the compiler
• NEVER skip CSpec validation or user confirmation

References

MCP Tools Used

Bridge supports two Figma MCP transports. Tool names vary by transport — see references/transport-adapter.md for the full mapping table and adaptation rules.