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

Command	Action File	Purpose
make <description>	references/actions/make.md	Spec + generate + verify (unified flow)
fix	references/actions/fix.md	Diff corrections, learn, iterate
done	references/actions/done.md	Archive, recipe extraction, ship
setup	references/actions/setup.md	DS extraction + KB build
status	(inline below)	Show current state
drop	references/actions/drop.md	Abandon with preserved learnings

---

Action Router

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

User says	Route to
"make", "design", "create", "build", "generate", "new component", "new screen"	references/actions/make.md
"fix", "correct", "learn", "diff", "corrections", "what changed", "I adjusted"	references/actions/fix.md
"done", "ship", "ship it", "finish", "complete", "close"	references/actions/done.md
"setup", "extract", "extract DS", "build knowledge base", "onboard"	references/actions/setup.md
"status", "workflow", "what's next", "what now"	(status logic below)
"drop", "abandon", "cancel"	references/actions/drop.md

---

Context Loading Rules (CRITICAL)

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

Action	Required references
make	compiler-reference.md + transport-adapter.md + actions/make.md
fix	transport-adapter.md + actions/fix.md
done	actions/done.md
setup	transport-adapter.md + actions/setup.md
drop	actions/drop.md

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)

State	Suggestion
No knowledge base	"Run: setup to extract and document your DS"
No active CSpec	"Ready. Run: make <description>"
Active CSpec, no snapshot	"CSpec ready but not yet compiled. Run: make to continue"
Active CSpec + snapshot	"Design generated. Try it in Figma, then: fix or done"
DS may be outdated	"Run: setup to refresh registries from Figma"

---

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

Reference	Path
Compiler reference	references/compiler-reference.md
Transport adapter	references/transport-adapter.md
Quality gates	references/quality-gates.md
CSpec template (screen)	references/templates/screen-cspec.yaml
CSpec template (component)	references/templates/component-cspec.yaml
Recipe system	references/knowledge-base/recipes/README.md

---

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.

Operation	Console transport	Official transport
Execute Plugin API code	figma_execute	use_figma
Take screenshot	figma_take_screenshot	get_screenshot
Full DS extraction	figma_get_design_system_kit	Composite strategy
Get variables	figma_get_variables	get_variable_defs
Get styles	figma_get_styles	search_design_system
Search components	figma_search_components	search_design_system
Connection check	figma_get_status	whoami