@noemuch/bridge-ds 2.2.0 → 2.5.0

package/lib/scaffold.js

@@ -5,7 +5,7 @@ const path = require('path');
  * Recursively copy a directory, preserving structure.
  * @param {string[]} skipDirs - directory names to skip (e.g., ['registries', 'guides', 'ui-references'])
  */
-function copyDir(src, dest, skipDirs = []) {
+function copyDir(src, dest, skipDirs = [], skipFiles = []) {
   const created = [];
   if (!fs.existsSync(dest)) {
     fs.mkdirSync(dest, { recursive: true });
@@ -15,8 +15,9 @@ function copyDir(src, dest, skipDirs = []) {
     const destPath = path.join(dest, entry.name);
     if (entry.isDirectory()) {
       if (skipDirs.includes(entry.name)) continue;
-      created.push(...copyDir(srcPath, destPath, skipDirs));
+      created.push(...copyDir(srcPath, destPath, skipDirs, skipFiles));
     } else {
+      if (skipFiles.includes(entry.name)) continue;
       fs.copyFileSync(srcPath, destPath);
       created.push(destPath);
     }
@@ -102,6 +103,7 @@ function scaffold(projectDir) {
     '.claude/skills/design-workflow/references/knowledge-base/registries/*.json',
     '.claude/skills/design-workflow/references/knowledge-base/ui-references/screenshots/*.png',
     '.claude/skills/design-workflow/references/knowledge-base/ui-references/screenshots/*.jpg',
+    '.claude/skills/design-workflow/references/knowledge-base/learnings.json',
   ];
   const gitignoreBlock = gitignoreEntries.join('\n') + '\n';
 
@@ -137,7 +139,8 @@ function update(projectDir) {
 
   // Copy skill files, skipping user-generated KB data
   const userDataDirs = ['registries', 'guides', 'ui-references'];
-  const files = copyDir(skillsSrc, skillsDest, userDataDirs);
+  const userDataFiles = ['learnings.json'];
+  const files = copyDir(skillsSrc, skillsDest, userDataDirs, userDataFiles);
   updated.push(...files.map(f => path.relative(projectDir, f)));
 
   // Update command file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noemuch/bridge-ds",
-  "version": "2.2.0",
+  "version": "2.5.0",
   "description": "AI-powered design generation in Figma — 100% design system compliant. Connects Claude Code to Figma via MCP for spec-first, token-bound, component-native design.",
   "main": "lib/cli.js",
   "bin": {
@@ -12,7 +12,12 @@
     "skills/",
     "commands/",
     "README.md",
-    "LICENSE"
+    "CHANGELOG.md",
+    "LICENSE",
+    ".claude-plugin/",
+    ".cursor-plugin/",
+    ".mcp.json",
+    "CLAUDE.md"
   ],
   "engines": {
     "node": ">=18"
@@ -27,7 +32,9 @@
     "mcp",
     "design-tokens",
     "ai-design",
-    "figma-plugin-api"
+    "figma-plugin-api",
+    "claude-code-plugin",
+    "cursor-plugin"
   ],
   "author": "noemuch",
   "license": "MIT",

package/skills/design-workflow/SKILL.md

@@ -5,14 +5,14 @@ description: >
   Covers components and full interfaces/screens. Use when a designer wants to:
   (1) write or review a component or screen spec, (2) generate a Figma design via MCP,
   (3) review and iterate on a design, (4) close or abandon work.
-  Triggers: "spec", "design", "screen", "review", "done", "drop", "status",
-  "setup", "workflow", "what's next", "new component", "new screen", or any design request.
+  Triggers: "spec", "design", "screen", "review", "done", "drop", "learn", "sync",
+  "status", "setup", "quick", "express", "fast", "workflow", "what's next", "new component", "new screen", or any design request.
 ---
 
 # Design Workflow
 
 > Spec-first workflow for designers using Claude Code to design in Figma.
-> Powered by [figma-console-mcp](https://github.com/southleft/figma-console-mcp) as transport.
+> Powered by Figma MCP transport (console or official). See `references/transport-adapter.md`.
 > **All output in the user's language.**
 
 ---
@@ -28,6 +28,18 @@ description: >
 
 ---
 
+## 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 `/design-workflow 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.
+
+---
+
 ## Commands
 
 | Command | Purpose | Action file |
@@ -38,7 +50,19 @@ description: >
 | `review` | Validate design against spec, tokens, and visual fidelity | `references/actions/review.md` |
 | `done` | Archive spec and close | `references/actions/done.md` |
 | `drop` | Abandon with preserved learnings | `references/actions/drop.md` |
+| `learn` | Diff design vs corrections, extract learnings | `references/actions/learn.md` |
+| `sync` | Incremental DS sync (no full re-setup) | `references/actions/sync.md` |
 | `status` | Show current state and suggest next action | *(inline below)* |
+| `quick {description}` | Express generation — skip spec, generate directly | `references/actions/quick.md` |
+| `express {description}` | Alias for quick | `references/actions/quick.md` |
+| `fast {description}` | Alias for quick | `references/actions/quick.md` |
+
+---
+
+### Express Mode
+For rapid generation without formal specs, use `quick`. Requires an existing knowledge base.
+Full quality gates still apply for DS compliance and token binding.
+See `references/actions/quick.md`.
 
 ---
 
@@ -70,7 +94,7 @@ The `spec` action auto-detects the mode from context, or asks the user.
 
 ```
 setup (first time only)
-  → Extract DS via figma-console-mcp
+  → Extract DS via Figma MCP transport
   → Build knowledge base (registries + guides)
   ↓
 spec {name}
@@ -105,7 +129,32 @@ review
   │     3. Verdict: PASS / FAIL with identified gaps
   │
   ▼
+(optional) user corrects in Figma
+  │
+  ▼
+learn (optional, repeatable)
+  │
+  ├─ Diff snapshot vs current Figma state
+  ├─ Classify: DS-compliant → learning | hardcoded → flag
+  ├─ Persist to learnings.json
+  └─ Update spec with corrections
+  │
+  ▼
 done
+  │
+  ├─ Persist learnings
+  ├─ Archive spec
+  └─ Cleanup snapshot
+
+───────────────────────────────
+
+sync (independent, anytime)
+  │
+  ├─ Re-extract DS via MCP
+  ├─ Diff vs current registries
+  ├─ Report: +added, ~modified, -removed
+  ├─ Breaking change analysis
+  └─ Update registries + patch guides
 ```
 
 ---
@@ -122,7 +171,10 @@ Detect intent from user input and **read the action file BEFORE executing**:
 | "review", "check", "validate", "audit" | `references/actions/review.md` |
 | "done", "finish", "complete", "close", "ship" | `references/actions/done.md` |
 | "drop", "abandon", "cancel" | `references/actions/drop.md` |
+| "learn", "diff", "corrections", "what changed" | `references/actions/learn.md` |
+| "sync", "update DS", "refresh DS", "sync DS" | `references/actions/sync.md` |
 | "status", "workflow", "what's next", "what now" | *(status logic below)* |
+| "quick", "express", "fast", "quick design", "just design" | `references/actions/quick.md` |
 
 ---
 
@@ -152,7 +204,8 @@ Detect state by checking:
 | No spec | "Ready. Run: `spec {name}`" |
 | Active spec, no Figma design | "Spec ready. Run: `design`" |
 | Active spec + Figma done | "Design ready. Run: `review`" |
-| Review passed | "Run: `done`" |
+| Review passed | "Run: `done` (or `learn` if you made manual corrections)" |
+| DS may be outdated | "Run: `sync` to update registries from Figma" |
 
 ---
 
@@ -179,6 +232,7 @@ Full definitions: `references/quality-gates.md` (read before any phase transitio
 
 | Reference | Path |
 |-----------|------|
+| Transport adapter | `references/transport-adapter.md` |
 | Quality gates | `references/quality-gates.md` |
 | Figma API rules | `references/figma-api-rules.md` |
 | Onboarding flow | `references/onboarding.md` |
@@ -191,15 +245,14 @@ Full definitions: `references/quality-gates.md` (read before any phase transitio
 
 ## MCP Tools Used
 
-Bridge uses [figma-console-mcp](https://github.com/southleft/figma-console-mcp) for all Figma operations:
-
-| Tool | Usage |
-|------|-------|
-| `figma_execute` | Run Figma Plugin API code (create frames, import components, bind variables) |
-| `figma_take_screenshot` | Visual verification between atomic steps |
-| `figma_get_design_system_kit` | Extract full DS (tokens + components + styles) during setup |
-| `figma_get_variables` | Extract design tokens/variables |
-| `figma_get_component` | Get component specs and properties |
-| `figma_get_styles` | Get text, color, effect styles |
-| `figma_search_components` | Find components by name |
-| `figma_get_status` | Check Figma connection |
+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` |

package/skills/design-workflow/references/actions/design.md

@@ -1,13 +1,15 @@
 # Action: design
 
-> Generate a Figma design from the active spec via figma-console-mcp.
+> Generate a Figma design from the active spec via Figma MCP transport.
+>
+> **Before generating, check `references/transport-adapter.md` to determine the active transport.** Tool names and script format vary by transport.
 
 ---
 
 ## Prerequisites
 
 - Active spec in `specs/active/` (abort if missing: "No active spec. Run: `spec {name}`")
-- figma-console-mcp MCP server available (check with `figma_get_status`)
+- Figma MCP transport available (console: `figma_get_status`, official: `whoami` — see transport-adapter.md Section F)
 - **If screen spec lists "New DS Components Required"**: all listed components MUST be spec'd and designed first. Abort and prompt: "New component `{name}` needs to be created first. Run: `spec {name}`"
 
 ---
@@ -44,7 +46,25 @@ Parse from spec:
 **Load Figma API rules (CRITICAL — read before writing any script):**
 - `references/figma-api-rules.md` → all API patterns, variable binding, boilerplate
 
-All paths relative to `.claude/skills/design-workflow/references/knowledge-base/`.
+All paths relative to `references/knowledge-base/`.
+
+### 1e. Load Learnings
+
+Load `references/knowledge-base/learnings.json` (skip if file doesn't exist — no learnings yet).
+
+Filter applicable learnings:
+- **Global learnings** (`scope: "global"`): always apply
+- **Contextual learnings** (`scope: "contextual"`): match by `screenType` (from spec's description), `component`, or `section`
+
+Display matched learnings before generation:
+```
+KNOWN PREFERENCES ({n} learnings):
+─────────────────────────────────
+• {rule} (signals: {n}, scope: {scope})
+• {rule} (signals: {n}, scope: {scope})
+```
+
+Integrate these into pre-script audits: when a script creates an element matching a learning's context, use the learning's `to` token instead of the default.
 
 **Registry key validation (BLOCKING):**
 Before using any registry, verify that entries contain `key` fields (not just `id` or `name`):
@@ -69,7 +89,53 @@ Key rules applied: {bullet list}
 
 **GATE: If no pattern matches**, ask the user which existing pattern is closest.
 
-### 1c. Canvas dimensions
+### 1c. Reference Inspection (BLOCKING for screens with reference)
+
+**If the spec has a "Reference Screen" section with a Figma URL/node ID, this step is MANDATORY.**
+
+1. **Screenshot the reference** (console: `figma_take_screenshot({ node_id, file_key })`, official: `get_screenshot({ nodeId, fileKey })`)
+2. **Inspect the reference structure** via Plugin API (console: `figma_execute`, official: `use_figma` with fileKey+description) — extract the node tree:
+   ```js
+   return (async function() {
+     var ref = await figma.getNodeByIdAsync("REFERENCE_NODE_ID");
+     if (!ref) return { error: "Node not found" };
+     var children = [];
+     for (var i = 0; i < ref.children.length; i++) {
+       var c = ref.children[i];
+       children.push({
+         name: c.name, type: c.type, id: c.id,
+         width: Math.round(c.width), height: Math.round(c.height),
+         isComponent: c.type === "INSTANCE" || c.type === "COMPONENT",
+         componentName: c.type === "INSTANCE" ? c.mainComponent.name : undefined
+       });
+     }
+     return { name: ref.name, width: Math.round(ref.width), height: Math.round(ref.height), children: children };
+   })();
+   ```
+3. **Document findings** before proceeding:
+   ```
+   Reference inspection:
+   - Shell structure: {sidebar Xpx | content FILL | buffer Xpx}
+   - DS components found: {list with node IDs}
+   - Local/unpublished elements: {list with node IDs — these need cloning}
+   - Logo variant: {exact name}
+   - Key differences from spec: {what content changes}
+   ```
+4. **Update generation strategy:**
+   - Elements found in reference → plan to **clone** (faster, guaranteed match)
+   - Elements in DS registry but not in reference → plan to **import**
+   - Update the pre-script audit to reflect clone vs import per element
+
+**GATE:** Do not generate until reference inspection is complete and strategy is documented.
+
+**If no reference provided (building from scratch):** Skip this step but warn the user:
+```
+No reference screen provided. Building layout from scratch.
+This may require more iterations. For better results, provide a Figma URL
+of an existing screen with a similar layout shell.
+```
+
+### 1d. Canvas dimensions
 
 - **Web**: 1440px wide
 - **Mobile**: 390px wide
@@ -81,30 +147,40 @@ Ask the user:
 - **Which Figma file?** (URL or fileKey)
 - **Which page?** (or create a new page)
 
-Verify connection:
+Verify connection (transport-neutral — see transport-adapter.md Section F):
 ```
-figma_get_status()
+Console: figma_get_status()
+Official: whoami() + test use_figma call
 ```
 
 **Library activation check:** Verify DS libraries are **enabled** in the target file. `importComponentByKeyAsync` only works with published AND enabled libraries.
 
 ### 3. Generate the design — Atomic Steps
 
-Write and execute Figma Plugin API scripts via `figma_execute`.
+Write and execute Figma Plugin API scripts (console: `figma_execute`, official: `use_figma` — see `references/transport-adapter.md` Section C for script format).
 
 **Before writing any script, read `references/figma-api-rules.md`.** It contains:
 - Mandatory patterns (FILL after appendChild, variable binding, font loading)
 - DS component reuse rules (Rule 18) and canvas positioning (Rule 19)
 - Standard script boilerplate with helpers
 
-**Script execution via MCP:**
+**Script execution via MCP (format depends on transport — see transport-adapter.md Section C):**
+
+Console:
 ```
 figma_execute({
   code: "return (async function() { ... your Plugin API code ... return { success: true }; })();"
 })
 ```
 
-The `return` before the IIFE is mandatory — without it, the Promise is lost.
+Official:
+```
+use_figma({
+  fileKey: "...",
+  description: "Step N: ...",
+  code: "await figma.loadFontAsync(...); ... return { success: true };"
+})
+```
 
 **Atomic generation (MANDATORY approach):**
 
@@ -156,9 +232,10 @@ NEVER recreate as raw frame/text/shape. NEVER hardcode hex colors — always bin
 | 3. Bind props | `componentPropertyReferences` on all nodes | ~30-40 | — |
 | 4. Refinements | Adjust spacing, sizing, visual polish | ~20-30 | — |
 
-**After each step:** verify visually with `figma_take_screenshot` before proceeding:
+**After each step:** verify visually with a screenshot before proceeding (console: `figma_take_screenshot({ node_id, file_key })`, official: `get_screenshot({ nodeId, fileKey })` — both require nodeId and fileKey):
 ```
-figma_take_screenshot({ node_id: "{rootOrSectionId}", file_key: "{fileKey}" })
+Console: figma_take_screenshot({ node_id: "{rootOrSectionId}", file_key: "{fileKey}" })
+Official: get_screenshot({ nodeId: "{rootOrSectionId}", fileKey: "{fileKey}" })
 ```
 Compare the screenshot against the spec and reference patterns. If something is wrong, fix it before moving to the next step.
 
@@ -198,6 +275,26 @@ Only create raw elements for pure layout frames or when no DS component exists (
 
 Verify all layers have semantic names (no "Frame", "Rectangle", "Group").
 
+### 6. Save Snapshot
+
+After successful generation, save a snapshot of the design's node tree for future `learn` diffing.
+
+1. Run the node tree extraction script from `schemas/learnings.md` via `figma_execute`, using the root node ID from step 3
+2. Save to `specs/active/{name}-snapshot.json` with structure:
+   ```json
+   {
+     "meta": {
+       "spec": "{name}",
+       "generatedAt": "{ISO timestamp}",
+       "rootNodeId": "{rootId}",
+       "fileKey": "{fileKey}"
+     },
+     "tree": { ... extracted node tree ... }
+   }
+   ```
+
+This snapshot enables the `learn` action to detect user corrections later.
+
 ---
 
 ## Output

package/skills/design-workflow/references/actions/done.md

@@ -26,15 +26,32 @@ Append to `specs/history.log`:
 {date} | {name} | {component|screen} | {figma_url} | {author}
 ```
 
-### 4. Brief retro
+### 4. Persist learnings
+
+Check if `learn` was run during this cycle (i.e., `references/knowledge-base/learnings.json` was updated with entries referencing this spec):
+
+- If yes: learnings are already persisted — confirm count:
+  ```
+  Learnings persisted: {n} learnings, {n} flags from this spec.
+  ```
+- If no learnings exist yet but a snapshot exists (`specs/active/{name}-snapshot.json`):
+  ```
+  💡 A snapshot exists but `learn` was never run.
+     If you made manual corrections in Figma, run `learn` before `done` to capture them.
+     Skip? (learnings will be lost)
+  ```
+  If user skips, proceed. If not, abort and let them run `learn` first.
+
+### 5. Brief retro
 
 - **What went well?** (patterns to repeat)
 - **What was friction?** (improvements for the workflow)
 - **What was learned?** (reusable knowledge)
 
-### 5. Cleanup
+### 6. Cleanup
 
-Delete any remaining temp files if not already done.
+- Delete snapshot file: `specs/active/{name}-snapshot.json` (if exists)
+- Delete any remaining temp files
 
 ---
 
@@ -45,4 +62,5 @@ Delete any remaining temp files if not already done.
 
 Figma: {url}
 Spec archived: specs/shipped/{name}-spec.md
+Learnings: {n} persisted
 ```

package/skills/design-workflow/references/actions/learn.md

@@ -0,0 +1,147 @@
+# Action: learn
+
+> Diff the generated design against the current Figma state, extract user corrections, and persist learnings.
+
+---
+
+## Prerequisites
+
+- Active spec in `specs/active/` (abort if missing: "No active spec. Run: `spec {name}`")
+- Snapshot file exists at `specs/active/{name}-snapshot.json` (abort if missing: "No snapshot found. The design must have been generated with the latest workflow. Re-run: `design`")
+- Figma MCP transport available (console: `figma_get_status`, official: `whoami` — see `references/transport-adapter.md` Section F)
+
+---
+
+## Procedure
+
+### 1. Load artifacts
+
+- Read the active spec from `specs/active/{name}-spec.md`
+- Read the snapshot from `specs/active/{name}-snapshot.json`
+- Read existing learnings from `references/knowledge-base/learnings.json` (create empty structure if file doesn't exist)
+- Load `references/knowledge-base/registries/variables.json` → for token resolution
+
+### 2. Re-extract current state
+
+Run the same node tree extraction script used for snapshots (see `schemas/learnings.md`) via Plugin API execution, using the `rootNodeId` and `fileKey` from the snapshot's `meta`.
+
+```
+Console: figma_execute({ code: "...extraction script with ROOT_NODE_ID from snapshot meta..." })
+Official: use_figma({ fileKey: "...", description: "Re-extract node tree for learn diff", code: "...same script without IIFE wrapper..." })
+```
+
+See `references/transport-adapter.md` Section C for script format differences.
+
+### 3. Diff snapshot vs current state
+
+Compare the two JSON trees in context. Claude performs this comparison directly — no custom diff code needed.
+
+**Match strategy:**
+- Match nodes by `id` (stable across edits)
+- For each matched node, compare: `layoutMode`, `itemSpacing`, `paddingTop/Bottom/Left/Right`, `cornerRadius`, `fills`, `boundVariables`, `width`, `height`, `componentKey`
+- Detect **added nodes** (present in current, absent in snapshot)
+- Detect **removed nodes** (present in snapshot, absent in current)
+- Detect **property changes** (same node, different values)
+
+**Ignore:**
+- Pure name changes (layer renaming)
+- Position changes (x, y) unless they indicate a structural move
+
+### 4. Classify changes
+
+For each detected change:
+
+```
+Does the new value use a DS token (bound variable)?
+  → YES: Classify as LEARNING
+  → NO (hardcoded hex, raw px value, unbound): Classify as FLAG
+```
+
+**Token resolution:** Check `boundVariables` in the current tree. If the property has a bound variable ID, resolve it against `registries/variables.json` to get the token name.
+
+### 5. Extract learnings
+
+For each LEARNING-classified change:
+
+1. **Determine context:**
+   - `screenType`: from the spec's description or visual reference section
+   - `component`: nearest component ancestor name, or the node's own name if it's a component instance
+   - `section`: parent frame name (e.g., "header", "content", "sidebar")
+
+2. **Check for existing learning:** Search `learnings.json` for a learning with matching `context` + `change.property` + `change.to.token`
+   - If found: increment `signals`, append to `history`
+   - If not found: create new learning entry
+
+3. **Generate rule:** Write a human-readable rule describing the preference (e.g., "For settings screens, cards use spacing/medium (not large)")
+
+4. **Check promotion:** After updating signals, check if any contextual learning qualifies for global promotion:
+   - `signals >= 3`
+   - Observations from ≥ 2 different `screenType` values
+   - No contradiction (same property pointing to different tokens in different learnings)
+
+### 6. Extract flags
+
+For each FLAG-classified change:
+
+1. Create a flag entry with the spec name, node description, and what was hardcoded
+2. Add to `flags` array in `learnings.json`
+
+### 7. Update spec
+
+If learnings were extracted (DS-compliant changes):
+- Update the active spec's token references to match the corrected values
+- This ensures the spec in `specs/shipped/` (after `done`) reflects the final design
+
+### 8. Save learnings
+
+Write updated `learnings.json` to `references/knowledge-base/learnings.json`.
+
+Update `meta.lastUpdated` to today's date.
+
+### 9. Report
+
+```markdown
+## Learn: {name}
+
+### Changes detected: {total count}
+
+### Learnings extracted: {count}
+| # | Context | Property | From | To | Rule |
+|---|---------|----------|------|----|------|
+| 1 | settings / card | itemSpacing | spacing/large (24) | spacing/medium (16) | Cards in settings use medium spacing |
+
+### Flags: {count}
+| # | Node | Issue |
+|---|------|-------|
+| 1 | StatusBadge | Hardcoded hex #FF5722 — no DS token bound |
+
+### Promotions: {count}
+- "{rule}" promoted to global (signals: {n}, screenTypes: {list})
+
+### Spec updated: {yes/no}
+{list of spec changes if any}
+
+Next: Continue editing in Figma and run `learn` again, or run: `done`
+```
+
+---
+
+## Output
+
+```
+Learn complete for {name}.
+
+Learnings: {n} extracted ({n} new, {n} reinforced, {n} promoted)
+Flags: {n} hardcoded values flagged
+Spec: {updated/unchanged}
+
+Learnings saved to knowledge-base/learnings.json
+Next: `done` to archive, or continue editing and `learn` again.
+```
+
+---
+
+## Transition
+
+- If user wants to continue editing → they can run `learn` again after more changes
+- When satisfied → suggest: "Run: `done`"

package/skills/design-workflow/references/actions/quick.md

@@ -0,0 +1,78 @@
+# Quick Mode — Express Design Generation
+
+## Purpose
+Generate a Figma design directly from a brief description, skipping the formal spec phase. Uses existing knowledge base, registries, and learnings. For when you need speed over ceremony.
+
+## Prerequisites
+- Knowledge base exists (registries populated) — if not, suggest: "Run `/design-workflow setup` first"
+- MCP transport available (see transport-adapter.md)
+
+## Procedure
+
+### Step 1 — Load context
+1. Load all registries (components.json, variables.json, text-styles.json)
+2. Load all guides (token usage, component overview, design patterns)
+3. Load learnings.json (apply all with scope=global + contextual matching description)
+4. Load ui-references guide if available
+
+### Step 2 — Gather intent (2 questions max)
+Ask the user exactly two things:
+1. **What to design**: brief description (e.g., "a settings page with profile section and notification preferences")
+2. **Where**: Figma file URL or file key + page name
+
+Do NOT ask for detailed content, states, responsive rules, or acceptance criteria. Infer reasonable defaults from the knowledge base and design patterns.
+
+### Step 3 — Pattern matching (best-effort)
+- Identify the screen type from the description
+- Load matching design patterns from guides/design-patterns.md
+- If ui-references/screenshots exist, identify the closest reference
+- This step is NON-BLOCKING — if no pattern matches, proceed with reasonable layout defaults
+- Note: in full mode, pattern matching is a blocking gate. In quick mode, it is best-effort.
+
+### Step 4 — Generate mini-spec (inline, not persisted)
+Write a condensed spec covering only:
+- **Layout**: zones, grid, overall structure (1-2 sentences)
+- **Sections**: list of sections with DS components to use (table format)
+- **Tokens**: key tokens for the layout (background, spacing rhythm)
+- **Known Preferences**: applicable learnings from learnings.json
+
+Format as a concise markdown block. Do NOT write to specs/active/. This lives only in the conversation.
+
+Show the mini-spec to the user and ask: "Generate this design?" (single yes/no confirmation)
+
+### Step 5 — Generate design
+Follow the same generation procedure as design.md steps 3-6:
+1. Read figma-api-rules.md (MANDATORY — same rules apply in quick mode)
+2. Determine canvas dimensions based on screen type
+3. **Pre-script audit** (MANDATORY — list every element, cross-reference against registries)
+4. Generate atomically in 4-6 scripts, ~30-80 lines each
+5. Take screenshot after each atomic step for verification
+6. Fix any issues before proceeding to next step
+
+IMPORTANT: These gates are NOT relaxed in quick mode:
+- Pre-script element audit (Rule 18) — BLOCKING
+- Zero hardcoded hex colors — BLOCKING
+- Atomic generation with screenshots — MANDATORY
+- DS component reuse (never recreate) — BLOCKING
+
+### Step 6 — Present result
+Take a final screenshot of the complete design. Present to the user with:
+- Link to the Figma node
+- Summary of what was created (sections, components used, tokens applied)
+- Any learnings that were applied
+- Suggestion: "Run `/design-workflow review` for a formal quality check, or `/design-workflow learn` if you make corrections"
+
+## What is NOT done in quick mode
+- No formal spec file written to specs/active/
+- No formal review phase (but user can run review separately)
+- No automatic snapshot for learn (but user can run learn separately)
+- No pattern matching gate (best-effort only)
+- No acceptance criteria validation
+
+## Quality guarantee
+Even in quick mode, every design:
+- Uses 100% DS components (never raw recreations)
+- Uses 100% bound tokens (never hardcoded hex)
+- Is generated atomically with visual verification
+- Follows all 22+ figma-api-rules
+- Applies relevant learnings from previous corrections