design-workflow

Category: Docs & Knowledge | Uploader: noemuch | Downloads: 0 | Version: v1.0（Latest）

Compiler-driven design workflow for designers who use Claude Code to design in Figma. Covers components and full interfaces/screens. Use when a designer wants to: (1) make a new design (spec + compile + execute), (2) fix corrections and learn, (3) ship a completed design, (4) set up the knowledge base, or (5) check status.

Changelog: Source: GitHub https://github.com/noemuch/bridge

Directory Structure

Current level: tree/main/skills/design-workflow/

📁 references/
- 📁 actions/
  - 📄 done.md 3.5 KB
  - 📄 drop.md 1.2 KB
  - 📄 fix.md 6.3 KB
  - 📄 make.md 11.3 KB
  - 📄 setup.md 6.0 KB
- 📁 knowledge-base/
  - 📁 recipes/
    
    📄 _index.json 73 B
    
    📄 README.md 7.2 KB
  - 📁 schemas/
    
    📄 assets.md 3.9 KB
    
    📄 components.md 3.9 KB
    
    📄 learnings.md 9.9 KB
    
    📄 recipes.md 8.4 KB
    
    📄 text-styles.md 3.2 KB
    
    📄 validation.md 6.0 KB
    
    📄 variables.md 5.2 KB
  - 📄 README.md 4.5 KB
- 📁 templates/
  - 📄 component-cspec.yaml 9.0 KB
  - 📄 screen-cspec.yaml 13.9 KB
- 📄 compiler-reference.md 8.4 KB
- 📄 quality-gates.md 4.6 KB
- 📄 transport-adapter.md 7.3 KB
📄 SKILL.md 8.5 KB

SKILL.md

---
name: design-workflow
description: >
  Compiler-driven design workflow for designers who use Claude Code to design in Figma.
  Covers components and full interfaces/screens. Use when a designer wants to:
  (1) make a new design (spec + compile + execute), (2) fix corrections and learn,
  (3) ship a completed design, (4) set up the knowledge base, or (5) check status.
  Triggers: "make", "design", "create", "build", "generate", "fix", "correct",
  "learn", "done", "ship", "setup", "extract", "status", "drop", "abandon",
  "new component", "new screen", or any design request.
---

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

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

design-workflow

Directory Structure

SKILL.md

Report

Notice