@noemuch/bridge-ds 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noemuch/bridge-ds",
-  "version": "2.0.0",
+  "version": "2.1.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": {

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

@@ -46,6 +46,12 @@ Parse from spec:
 
 All paths relative to `.claude/skills/design-workflow/references/knowledge-base/`.
 
+**Registry key validation (BLOCKING):**
+Before using any registry, verify that entries contain `key` fields (not just `id` or `name`):
+- Components must have `key` (hex hash like `"abc123..."`) — NOT node IDs like `"1008:174"`
+- Variables must have `key` — NOT just name paths like `"color/background/neutral/boldest"`
+- If ANY registry is missing `key` fields → **STOP** and run `schemas/validation.md` procedure before continuing
+
 ### 1b. Pattern Matching (BLOCKING)
 
 **This step is MANDATORY. No design generation without completing it.**
@@ -109,14 +115,26 @@ Never generate a full design in a single script. Split into small, sequential st
 
 **CRITICAL — Pre-script element audit (BLOCKING, Rule 18):**
 
-Before writing EACH script, list every visual element it will create and verify against registries:
+Before writing EACH script, list every visual element it will create and cross-reference against the spec's "DS Components Used" table AND the registries:
+
 ```
-Elements in this step:
-- Avatar → components.json key: xxx ✓
-- Divider → components.json key: xxx ✓
-- Label text → raw text (layout frame label, no DS component) ✓
+PRE-SCRIPT AUDIT — Step {n}:
+Spec requires:           Registry match:              Script will use:
+─────────────────────────────────────────────────────────────────────
+AssetLogo (logo)       → logos.json key: abc123       → importComponentByKeyAsync ✓
+Tag v2 (label)         → components.json key: def456  → importComponentSetByKeyAsync ✓
+CardBase (container)   → components.json key: ghi789  → importComponentByKeyAsync ✓
+Section title          → NO DS component              → raw text (justified) ✓
+Layout wrapper         → NO DS component              → raw frame (structural) ✓
 ```
-If an element exists in `components.json`, it MUST be imported via `importComponentByKeyAsync`. NEVER recreate as raw frame/text/shape. NEVER hardcode hex colors — always bind variables.
+
+**BLOCKING RULES:**
+- If a spec-listed DS component is planned as a raw element → **STOP. Rewrite the script.**
+- If an element exists in ANY registry (components, icons, logos, illustrations) → **MUST import it**. No exceptions.
+- If you're about to use `figma.createEllipse()`, `figma.createRectangle()`, or `figma.createFrame()` for something that looks like a DS component → **STOP and check registries first.**
+- Only create raw elements for pure structural layout frames or when NO DS component exists (document WHY in the audit).
+
+NEVER recreate as raw frame/text/shape. NEVER hardcode hex colors — always bind variables.
 
 **Standard steps for a screen:**
 

package/skills/design-workflow/references/figma-api-rules.md

@@ -159,10 +159,10 @@ text.fontSize = 32;
 
 // CORRECT (key from registries/text-styles.json)
 var style = await figma.importStyleByKeyAsync("YOUR_TEXT_STYLE_KEY");
-text.textStyleId = style.id;
+await text.setTextStyleIdAsync(style.id);  // MUST use async version — see Rule 21
 ```
 
-**Load text style keys from `registries/text-styles.json`.**
+**Load text style keys from `registries/text-styles.json`.** Always use `setTextStyleIdAsync()`, not `textStyleId =`.
 
 ---
 
@@ -356,28 +356,38 @@ The `return` before the IIFE is mandatory — without it, the Promise is lost.
 
 ## Rule 18: DS component reuse — NEVER recreate existing components
 
-**This is the most critical rule. Violations require script rewrite.**
+**This is the most critical rule. Violations require FULL script rewrite.**
 
 Before creating ANY visual element, check the registries:
-1. `registries/components.json` → Buttons, Tags, Inputs, Avatars, Dividers, etc.
+1. `registries/components.json` → Buttons, Tags, Inputs, Avatars, Dividers, Cards, etc.
 2. `registries/icons.json` → Icons (if exists)
-3. `registries/logos.json` → Logos (if exists)
+3. `registries/logos.json` → Logos, brand assets (if exists)
 4. `registries/illustrations.json` → Illustrations (if exists)
 
 **NEVER:**
-- Create a raw frame/ellipse for an Avatar → import the DS component
-- Create a raw rectangle for a Divider → import the DS component
-- Create a raw frame with text for a Tag/Badge → import the DS component
+- `figma.createEllipse()` for a logo → import from logos.json via `importComponentByKeyAsync`
+- `figma.createFrame()` for a Tag/Badge → import from components.json via `importComponentSetByKeyAsync`
+- `figma.createFrame()` for a Card → import the DS Card component
+- `figma.createRectangle()` for a Divider → import the DS Divider component
 - Hardcode hex colors → always bind variables
 
-**Pre-script checklist (mandatory):**
+**Why this matters:** Using raw elements cascades into multiple failures:
+- No `INSTANCE_SWAP` props possible (can't swap a logo on an ellipse)
+- No inherited component properties (size, variant, state)
+- Wrong proportions (raw frames don't match DS component sizing)
+- Breaks the design system contract — the whole point of Bridge
+
+**Pre-script audit (MANDATORY — must appear before every script):**
 ```
-Elements in this step:
-- Avatar → components.json key: xxx ✓
-- Divider → components.json key: xxx ✓
-- Label → raw text (no DS component for this) ✓
+PRE-SCRIPT AUDIT — Step {n}:
+Spec requires:           Registry match:              Script will use:
+─────────────────────────────────────────────────────────────────────
+{element}              → {registry}.json key: {key}   → import{method} ✓
+{element}              → NO DS component              → raw {type} (reason) ✓
 ```
 
+**If ANY spec-listed DS component is planned as a raw element → STOP and fix before writing the script.**
+
 ---
 
 ## Rule 19: Canvas positioning — never stack components
@@ -400,6 +410,42 @@ mainComponent.y = 400;
 
 ---
 
+## Rule 20: Component key vs Node ID (CRITICAL)
+
+Figma components have TWO different identifiers:
+
+| | Node ID (`id`) | Component Key (`key`) |
+|---|---|---|
+| **Format** | `"1008:174"` (colon-separated numbers) | `"abc123def456..."` (hex hash) |
+| **Used for** | `figma.getNodeByIdAsync()` | `importComponentByKeyAsync()` |
+| **Available from** | Any node | Only published components/variables/styles |
+
+**These are NOT interchangeable.** Import APIs (`importComponentByKeyAsync`, `importComponentSetByKeyAsync`, `importVariableByKeyAsync`, `importStyleByKeyAsync`) all require the `key`, NOT the `id`.
+
+Similarly, variables have:
+- `name`: `"color/background/neutral/boldest"` — human-readable path
+- `key`: `"VariableID:55:114"` or hex hash — for `importVariableByKeyAsync`
+
+**Always verify registries contain `key` fields before writing import scripts. If a registry only has `id` or `name` values, re-run extraction to capture keys.**
+
+---
+
+## Rule 21: setTextStyleIdAsync (not textStyleId) in dynamic-page context
+
+When running scripts via `figma_execute` (which uses `documentAccess: "dynamic-page"`), text style assignment MUST use the async API:
+
+```js
+// WRONG — crashes in dynamic-page context
+text.textStyleId = style.id;
+
+// CORRECT
+await text.setTextStyleIdAsync(style.id);
+```
+
+Same applies to `setFillStyleIdAsync`, `setStrokeStyleIdAsync`, `setEffectStyleIdAsync`.
+
+---
+
 ## Standard Script Boilerplate
 
 ```js

package/skills/design-workflow/references/knowledge-base/README.md

@@ -6,6 +6,13 @@ This directory contains your design system's complete documentation, generated b
 
 ```
 knowledge-base/
+  schemas/                       ← Registry format definitions (read during setup)
+    components.md                ← components.json schema (required fields, extraction scripts)
+    variables.md                 ← variables.json schema
+    text-styles.md               ← text-styles.json schema
+    assets.md                    ← icons/logos/illustrations schema
+    validation.md                ← Post-extraction validation procedure
+
   registries/                    ← Raw DS data (auto-extracted from Figma)
     components.json              ← Component names, keys, variants, properties
     variables.json               ← Variable names, keys, types, values by mode
@@ -42,10 +49,12 @@ knowledge-base/
 
 Run `/design-workflow setup` in Claude Code. Claude will:
 
-1. **Extract** your DS from Figma via `figma_get_design_system_kit`
-2. **Analyze** the raw data and write intelligent guides
-3. **Ask for screenshots** of your product's key screens
-4. **Generate** layout pattern documentation from the screenshots
+1. **Extract** your DS from Figma via MCP tools
+2. **Write registries** following the schemas in `schemas/` (every entry must have a `key` field)
+3. **Validate** registries by test-importing sample keys via `figma_execute`
+4. **Analyze** the raw data and write intelligent guides
+5. **Ask for screenshots** of your product's key screens
+6. **Generate** layout pattern documentation from the screenshots
 
 ## How to update
 

package/skills/design-workflow/references/knowledge-base/schemas/assets.md

@@ -0,0 +1,144 @@
+# Schema: icons.json, logos.json, illustrations.json
+
+> **Read this BEFORE writing asset registries during setup.**
+
+---
+
+## Required Structure (same for all 3 files)
+
+```json
+{
+  "meta": {
+    "source": "Library file name",
+    "fileKey": "FigmaFileKey",
+    "extractedAt": "YYYY-MM-DD",
+    "totalComponents": 344
+  },
+  "items": [
+    {
+      "name": "icon/utility/check",
+      "key": "abc123def456...",
+      "type": "COMPONENT"
+    },
+    {
+      "name": "icon/utility/chevron-up",
+      "key": "def789ghi012...",
+      "type": "COMPONENT"
+    }
+  ],
+  "categories": {
+    "utility": {
+      "description": "UI action and navigation icons",
+      "count": 280,
+      "namingPattern": "icon/utility/{name}"
+    },
+    "flag": {
+      "description": "Country flag icons",
+      "count": 40,
+      "namingPattern": "icon/flag/{country}"
+    }
+  }
+}
+```
+
+---
+
+## Field Requirements
+
+### Per asset entry (`items` array)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | **YES** | Component name/path |
+| `key` | **YES** | Component key for `importComponentByKeyAsync`. NOT a node ID. |
+| `type` | **YES** | `"COMPONENT"` or `"COMPONENT_SET"` |
+
+### Categories (documentation only)
+
+Categories provide human-readable organization and naming patterns. They help Claude find the right asset without scanning all items.
+
+---
+
+## Large Libraries (500+ items)
+
+For very large asset libraries (e.g., 1300+ financial logos), extracting every key upfront is impractical:
+
+1. **Extract keys for commonly-used items** (top 50-100) into the `items` array
+2. **Document naming patterns** in `categories` for the rest
+3. **On-demand extraction**: When a specific asset is needed during `design`, use `figma_execute` to search by name and get the key:
+
+```js
+return (async function() {
+  var node = figma.currentPage.findOne(function(n) {
+    return n.name === "TARGET_NAME" && (n.type === "COMPONENT" || n.type === "COMPONENT_SET");
+  });
+  if (node) {
+    return { name: node.name, key: node.key, type: node.type };
+  }
+  return { error: "Not found" };
+})();
+```
+
+---
+
+## How to Extract Keys
+
+### Via figma_execute
+
+```js
+return (async function() {
+  var results = [];
+  // Get all components on the current page
+  var nodes = figma.currentPage.findAll(function(n) {
+    return n.type === "COMPONENT" || n.type === "COMPONENT_SET";
+  });
+
+  for (var i = 0; i < nodes.length; i++) {
+    var n = nodes[i];
+    // Skip individual variants inside component sets
+    if (n.type === "COMPONENT" && n.parent && n.parent.type === "COMPONENT_SET") continue;
+
+    results.push({
+      name: n.name,
+      key: n.key,       // ← REQUIRED for importComponentByKeyAsync
+      type: n.type
+    });
+  }
+
+  return { items: results, total: results.length };
+})();
+```
+
+Run on each page of the asset library file. For multi-page libraries, run once per page.
+
+---
+
+## Usage in Scripts
+
+```js
+// Import icon by key (from registries/icons.json)
+var checkIcon = await figma.importComponentByKeyAsync("abc123def456...");
+var iconInstance = checkIcon.createInstance();
+
+// Import logo with variants by key
+var logo = await figma.importComponentSetByKeyAsync("xyz789...");
+var defaultVariant = logo.defaultVariant;
+var logoInstance = defaultVariant.createInstance();
+```
+
+---
+
+## File-specific Notes
+
+### icons.json
+- Icons are typically single components (`type: "COMPONENT"`)
+- Naming convention: `icon/{category}/{name}` (e.g., `icon/utility/check`)
+
+### logos.json
+- Logos may be component sets with mode variants (dark/light)
+- Naming convention: `{brand}` or `logo/{brand}/{variant}`
+
+### illustrations.json
+- Illustrations often have theme variants (dark/light/brand)
+- May be component sets (`type: "COMPONENT_SET"`)
+- Naming convention: `{category}/{name}` (e.g., `asset/crypto`, `utility/empty-state`)

package/skills/design-workflow/references/knowledge-base/schemas/components.md

@@ -0,0 +1,124 @@
+# Schema: components.json
+
+> **Read this BEFORE writing components.json during setup.**
+
+---
+
+## Required Structure
+
+```json
+{
+  "meta": {
+    "source": "Library file name",
+    "fileKey": "FigmaFileKey",
+    "extractedAt": "YYYY-MM-DD",
+    "totalComponents": 100,
+    "totalComponentSets": 76
+  },
+  "components": {
+    "categoryName": [
+      {
+        "name": "Button",
+        "key": "abc123def456789...",
+        "id": "1008:174",
+        "type": "COMPONENT_SET",
+        "variants": 150,
+        "properties": {
+          "label": "TEXT",
+          "hasTrailingIcon": "BOOLEAN",
+          "leadingIcon": "INSTANCE_SWAP",
+          "variant": "VARIANT(primary,secondary,ghost)",
+          "state": "VARIANT(default,hover,disabled)",
+          "size": "VARIANT(large,medium,small)"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Field Requirements
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | **YES** | Human-readable component name |
+| `key` | **YES** | Component key for `importComponentByKeyAsync` / `importComponentSetByKeyAsync`. A hex hash like `"abc123def456..."` (NOT a node ID). |
+| `id` | optional | Figma node ID like `"1008:174"`. Useful for lookups but NOT for imports. |
+| `type` | **YES** | `"COMPONENT"` or `"COMPONENT_SET"`. Determines which import API to use. |
+| `variants` | optional | Number of variants (only for COMPONENT_SET) |
+| `properties` | **YES** | Object mapping property names to types: `TEXT`, `BOOLEAN`, `INSTANCE_SWAP`, `VARIANT(...)` |
+
+---
+
+## CRITICAL: `key` vs `id`
+
+These are TWO DIFFERENT identifiers in Figma:
+
+| | `id` (node ID) | `key` (component key) |
+|---|---|---|
+| **Looks like** | `"1008:174"` | `"abc123def456789abcdef..."` |
+| **Used for** | `figma.getNodeById()` | `importComponentByKeyAsync()` |
+| **Available from** | Any node | Only published components |
+
+**`importComponentByKeyAsync` REQUIRES the `key`, NOT the `id`.** Using a node ID as a key will crash the script silently.
+
+---
+
+## How to Extract Keys
+
+### Option A: Via figma_execute (RECOMMENDED)
+
+```js
+return (async function() {
+  var results = [];
+  var nodes = figma.currentPage.findAll(function(n) {
+    return n.type === "COMPONENT_SET" || (n.type === "COMPONENT" && !n.parent.type !== "COMPONENT_SET");
+  });
+  for (var i = 0; i < nodes.length; i++) {
+    var n = nodes[i];
+    results.push({
+      name: n.name,
+      key: n.key,        // ← THIS is what importComponentByKeyAsync needs
+      id: n.id,          // ← This is just the node ID (different!)
+      type: n.type,
+      variants: n.type === "COMPONENT_SET" ? n.children.length : undefined,
+      properties: n.type === "COMPONENT_SET" ? n.componentPropertyDefinitions : undefined
+    });
+  }
+  return { components: results };
+})();
+```
+
+Run this script on each page of the DS library file.
+
+### Option B: Via figma_get_design_system_kit
+
+If the MCP tool returns component data, look for the `key` field in the response. If only `id` is returned, use Option A to get the actual keys.
+
+---
+
+## Import API Decision
+
+| `type` value | Import API |
+|---|---|
+| `COMPONENT_SET` | `figma.importComponentSetByKeyAsync(key)` |
+| `COMPONENT` | `figma.importComponentByKeyAsync(key)` |
+
+Check the `type` field to decide which API to use. Using the wrong one will fail.
+
+---
+
+## Category Grouping
+
+Group components by semantic category:
+- `actions` — Buttons, IconButtons, Links
+- `formControls` — Inputs, Selects, Checkboxes, Radios, Toggles
+- `dataDisplay` — Tables, Lists, Cards, Badges, Tags
+- `feedback` — Alerts, Toasts, Modals, Dialogs
+- `navigation` — Tabs, Sidebar, Breadcrumbs, Pagination
+- `layout` — Dividers, Spacers, Containers
+- `indicators` — Avatars, Status, Progress
+
+Use whatever categories match the DS's own organization.

package/skills/design-workflow/references/knowledge-base/schemas/text-styles.md

@@ -0,0 +1,117 @@
+# Schema: text-styles.json
+
+> **Read this BEFORE writing text-styles.json during setup.**
+
+---
+
+## Required Structure
+
+```json
+{
+  "meta": {
+    "source": "Library file name",
+    "fileKey": "FigmaFileKey",
+    "extractedAt": "YYYY-MM-DD",
+    "totalStyles": 56
+  },
+  "textStyles": {
+    "display": [
+      { "name": "display/lg", "key": "a9b866d18e77632daa1f4056b905af688933c4c7", "nodeId": "60:169" }
+    ],
+    "heading": [
+      { "name": "heading/xl/regular", "key": "930df26f44235299875c572ef52bd60cbf5ae956", "nodeId": "60:172" },
+      { "name": "heading/xl/accent", "key": "225299706052d97c6259e70545f448cb44e84f9f", "nodeId": "60:173" }
+    ],
+    "body": [
+      { "name": "body/lg/regular", "key": "fe5e50c7cbdc2b607aecb70747cfae7ac4da49ee", "nodeId": "60:206" }
+    ]
+  },
+  "effectStyles": {
+    "shadow": [
+      { "name": "shadow/xsmall", "key": "1b34455796052a6ec745a03064597491bb8db256", "nodeId": "2620:254" }
+    ]
+  },
+  "sizeMap": {
+    "display/lg": { "fontSize": 40, "lineHeight": 88, "fontFamily": "Inter" },
+    "heading/xl": { "fontSize": 40, "lineHeight": 48, "fontFamily": "Inter" }
+  }
+}
+```
+
+---
+
+## Field Requirements
+
+### Per text style entry
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | **YES** | Style name like `"heading/xl/regular"` |
+| `key` | **YES** | Style key (40-char hex hash) for `importStyleByKeyAsync` |
+| `nodeId` | optional | Figma node ID for reference |
+
+### sizeMap (optional but recommended)
+
+Maps style names to font specs for quick human reference. Not used in scripts (scripts use the `key` to import the full style).
+
+---
+
+## How to Extract Keys
+
+### Via figma_execute
+
+```js
+return (async function() {
+  var textStyles = await figma.getLocalTextStylesAsync();
+  var effectStyles = await figma.getLocalEffectStylesAsync();
+
+  var result = { textStyles: [], effectStyles: [] };
+
+  for (var i = 0; i < textStyles.length; i++) {
+    var s = textStyles[i];
+    result.textStyles.push({
+      name: s.name,
+      key: s.key,  // ← 40-char hex hash for importStyleByKeyAsync
+      nodeId: s.id,
+      fontSize: s.fontSize,
+      lineHeight: s.lineHeight,
+      fontFamily: s.fontName.family,
+      fontStyle: s.fontName.style
+    });
+  }
+
+  for (var i = 0; i < effectStyles.length; i++) {
+    var s = effectStyles[i];
+    result.effectStyles.push({
+      name: s.name,
+      key: s.key,
+      nodeId: s.id
+    });
+  }
+
+  return result;
+})();
+```
+
+---
+
+## Usage in Scripts
+
+```js
+// Import text style by key (from registries/text-styles.json)
+var headingStyle = await figma.importStyleByKeyAsync("930df26f44235299875c572ef52bd60cbf5ae956");
+await textNode.setTextStyleIdAsync(headingStyle.id);  // MUST use async version (Rule 20)
+```
+
+---
+
+## Grouping
+
+Group text styles by their first path segment:
+- `display` — Large hero/display text
+- `heading` — Section and page headings
+- `body` — Body copy, descriptions
+- `caption` — Small labels, metadata
+- `code` — Monospace / code text
+
+Weight/emphasis variants are the second segment: `regular`, `accent`, `emphasis`, `bold`.

package/skills/design-workflow/references/knowledge-base/schemas/validation.md

@@ -0,0 +1,182 @@
+# Registry Validation Procedure
+
+> **Run this AFTER writing all registries and BEFORE generating guides.**
+> This step is BLOCKING — do not proceed until all validations pass.
+
+---
+
+## Phase 1 — Structural Check
+
+Read each registry file and verify:
+
+### components.json
+- [ ] Every entry has a `key` field (hex hash, NOT a node ID with `:` separator)
+- [ ] Every entry has a `type` field (`"COMPONENT"` or `"COMPONENT_SET"`)
+- [ ] Every entry has a `properties` object
+- [ ] `key` values look like hex hashes (long alphanumeric strings), NOT like `"1008:174"`
+
+### variables.json
+- [ ] Every variable entry has a `key` field
+- [ ] Every variable entry has a `name` field (human-readable path)
+- [ ] Every variable entry has `valuesByMode`
+- [ ] `key` values are NOT the same as `name` values (names look like `color/background/...`, keys look like `VariableID:...` or hex hashes)
+
+### text-styles.json
+- [ ] Every text style entry has a `key` field (40-char hex hash)
+- [ ] Every entry has a `name` field
+
+### icons.json / logos.json / illustrations.json (if present)
+- [ ] Every entry in `items` array has a `key` field
+- [ ] Every entry has a `type` field
+
+**If ANY check fails:** Re-extract the failing registry using the extraction scripts in `schemas/components.md`, `schemas/variables.md`, etc.
+
+---
+
+## Phase 2 — Import Test
+
+Run a validation script via `figma_execute` that test-imports a sample of keys from each registry.
+
+### Validation Script Template
+
+```js
+return (async function() {
+  var results = [];
+
+  // ── TEST COMPONENT KEYS ──
+  // Pick 3-5 component keys from registries/components.json
+  var componentTests = [
+    { name: "COMPONENT_NAME_1", key: "KEY_1", type: "COMPONENT_SET" },
+    { name: "COMPONENT_NAME_2", key: "KEY_2", type: "COMPONENT" },
+    { name: "COMPONENT_NAME_3", key: "KEY_3", type: "COMPONENT_SET" }
+  ];
+
+  for (var i = 0; i < componentTests.length; i++) {
+    var t = componentTests[i];
+    try {
+      if (t.type === "COMPONENT_SET") {
+        await figma.importComponentSetByKeyAsync(t.key);
+      } else {
+        await figma.importComponentByKeyAsync(t.key);
+      }
+      results.push({ type: "component", name: t.name, status: "OK" });
+    } catch(e) {
+      results.push({ type: "component", name: t.name, status: "FAIL", error: e.message });
+    }
+  }
+
+  // ── TEST VARIABLE KEYS ──
+  // Pick 3-5 variable keys from registries/variables.json (mix of color + spacing)
+  var variableTests = [
+    { name: "VARIABLE_NAME_1", key: "KEY_1" },
+    { name: "VARIABLE_NAME_2", key: "KEY_2" },
+    { name: "VARIABLE_NAME_3", key: "KEY_3" }
+  ];
+
+  for (var i = 0; i < variableTests.length; i++) {
+    var t = variableTests[i];
+    try {
+      await figma.variables.importVariableByKeyAsync(t.key);
+      results.push({ type: "variable", name: t.name, status: "OK" });
+    } catch(e) {
+      results.push({ type: "variable", name: t.name, status: "FAIL", error: e.message });
+    }
+  }
+
+  // ── TEST TEXT STYLE KEYS ──
+  // Pick 2-3 text style keys from registries/text-styles.json
+  var styleTests = [
+    { name: "STYLE_NAME_1", key: "KEY_1" },
+    { name: "STYLE_NAME_2", key: "KEY_2" }
+  ];
+
+  for (var i = 0; i < styleTests.length; i++) {
+    var t = styleTests[i];
+    try {
+      await figma.importStyleByKeyAsync(t.key);
+      results.push({ type: "textStyle", name: t.name, status: "OK" });
+    } catch(e) {
+      results.push({ type: "textStyle", name: t.name, status: "FAIL", error: e.message });
+    }
+  }
+
+  // ── SUMMARY ──
+  var passed = results.filter(function(r) { return r.status === "OK"; }).length;
+  var failed = results.filter(function(r) { return r.status === "FAIL"; }).length;
+
+  return {
+    total: results.length,
+    passed: passed,
+    failed: failed,
+    results: results
+  };
+})();
+```
+
+### How to Use
+
+1. Read the registries you just wrote
+2. Pick sample keys from each (prioritize commonly-used components like Button, Input, Tag + core variables like spacing/medium, background colors + main text styles)
+3. Replace the placeholder names and keys in the script above
+4. Run via `figma_execute`
+5. Check results
+
+---
+
+## Phase 3 — Remediation
+
+If any keys fail validation:
+
+### Component key failed
+→ The key is likely a node ID instead of a component key. Re-extract using:
+```js
+return (async function() {
+  var node = await figma.getNodeByIdAsync("NODE_ID_FROM_REGISTRY");
+  if (node) {
+    return { name: node.name, correctKey: node.key, incorrectId: node.id };
+  }
+  return { error: "Node not found" };
+})();
+```
+Update the registry entry with the `correctKey`.
+
+### Variable key failed
+→ The key is likely the variable name instead of the variable key. Re-extract using:
+```js
+return (async function() {
+  var collections = await figma.variables.getLocalVariableCollectionsAsync();
+  for (var c = 0; c < collections.length; c++) {
+    for (var v = 0; v < collections[c].variableIds.length; v++) {
+      var variable = await figma.variables.getVariableByIdAsync(collections[c].variableIds[v]);
+      if (variable && variable.name === "VARIABLE_NAME") {
+        return { name: variable.name, correctKey: variable.key };
+      }
+    }
+  }
+  return { error: "Variable not found" };
+})();
+```
+
+### Text style key failed
+→ Likely a wrong key format. Re-extract using the script in `schemas/text-styles.md`.
+
+---
+
+## Validation Output
+
+After validation passes, log the summary:
+
+```
+Registry validation passed:
+- Components: {N}/{N} keys verified ✓
+- Variables: {N}/{N} keys verified ✓
+- Text styles: {N}/{N} keys verified ✓
+- Assets: {N}/{N} keys verified ✓ (or "skipped — no asset registries")
+
+All import tests passed. Proceeding to guide generation.
+```
+
+If validation fails after remediation attempts, ask the user to verify:
+1. The DS library is published (not just local)
+2. The library is enabled in the target Figma file
+3. The correct Figma file was used for extraction

package/skills/design-workflow/references/knowledge-base/schemas/variables.md

@@ -0,0 +1,153 @@
+# Schema: variables.json
+
+> **Read this BEFORE writing variables.json during setup.**
+
+---
+
+## Required Structure
+
+```json
+{
+  "meta": {
+    "source": "Library file name",
+    "fileKey": "FigmaFileKey",
+    "extractedAt": "YYYY-MM-DD",
+    "totalVariables": 856
+  },
+  "collections": {
+    "color": {
+      "id": "VariableCollectionId:19:113",
+      "modes": ["dark", "light"],
+      "variables": [
+        { "name": "color/background/neutral/boldest", "key": "VariableID:19:114", "valuesByMode": { "dark": "#FFFFFF", "light": "#000000" } },
+        { "name": "color/background/neutral/bolder", "key": "VariableID:19:115", "valuesByMode": { "dark": "#E5E5E5", "light": "#1A1A1A" } }
+      ]
+    },
+    "layout": {
+      "id": "VariableCollectionId:55:113",
+      "modes": ["value"],
+      "variables": [
+        { "name": "layout/spacing/none", "key": "VariableID:55:114", "valuesByMode": { "value": 0 } },
+        { "name": "layout/spacing/xsmall", "key": "VariableID:55:115", "valuesByMode": { "value": 8 } },
+        { "name": "layout/spacing/medium", "key": "VariableID:55:118", "valuesByMode": { "value": 16 } },
+        { "name": "layout/spacing/large", "key": "VariableID:55:119", "valuesByMode": { "value": 24 } },
+        { "name": "layout/radius/medium", "key": "VariableID:55:130", "valuesByMode": { "value": 12 } }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Field Requirements
+
+### Per variable entry
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | **YES** | Variable path like `"color/background/neutral/boldest"` |
+| `key` | **YES** | Variable key for `importVariableByKeyAsync`. Format varies (e.g., `"VariableID:55:114"` or a hash). |
+| `valuesByMode` | **YES** | Object mapping mode names to resolved values |
+
+### Per collection
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | optional | Collection ID |
+| `modes` | **YES** | Array of mode names |
+| `variables` | **YES** | Array of variable entries |
+
+---
+
+## CRITICAL: Variable `name` vs `key`
+
+These are TWO DIFFERENT things:
+
+| | `name` (path) | `key` (variable key) |
+|---|---|---|
+| **Looks like** | `"color/background/neutral/boldest"` | `"VariableID:55:114"` or hex hash |
+| **Used for** | Human reading, organization | `importVariableByKeyAsync()` |
+| **Available from** | `variable.name` | `variable.key` |
+
+**`importVariableByKeyAsync` REQUIRES the `key`, NOT the `name`.** The name is useful for documentation but cannot be used for script imports.
+
+---
+
+## How to Extract Keys
+
+### Via figma_execute (RECOMMENDED)
+
+```js
+return (async function() {
+  var collections = await figma.variables.getLocalVariableCollectionsAsync();
+  var result = {};
+
+  for (var c = 0; c < collections.length; c++) {
+    var col = collections[c];
+    var collectionData = {
+      id: col.id,
+      modes: col.modes.map(function(m) { return m.name; }),
+      variables: []
+    };
+
+    for (var v = 0; v < col.variableIds.length; v++) {
+      var variable = await figma.variables.getVariableByIdAsync(col.variableIds[v]);
+      if (!variable) continue;
+
+      var valuesByMode = {};
+      for (var m = 0; m < col.modes.length; m++) {
+        var mode = col.modes[m];
+        var val = variable.valuesByMode[mode.modeId];
+        // Resolve color values to hex
+        if (val && typeof val === "object" && "r" in val) {
+          var r = Math.round(val.r * 255).toString(16).padStart(2, "0");
+          var g = Math.round(val.g * 255).toString(16).padStart(2, "0");
+          var b = Math.round(val.b * 255).toString(16).padStart(2, "0");
+          valuesByMode[mode.name] = "#" + r + g + b;
+        } else if (val && typeof val === "object" && "type" in val) {
+          // Alias — store the referenced variable name
+          valuesByMode[mode.name] = "→ alias";
+        } else {
+          valuesByMode[mode.name] = val;
+        }
+      }
+
+      collectionData.variables.push({
+        name: variable.name,
+        key: variable.key,  // ← THIS is what importVariableByKeyAsync needs
+        valuesByMode: valuesByMode
+      });
+    }
+
+    // Use first segment of variable names as collection key (e.g., "color", "layout")
+    var collName = col.name.toLowerCase().replace(/\s+/g, "-");
+    result[collName] = collectionData;
+  }
+
+  return { collections: result };
+})();
+```
+
+### Important Notes
+
+- For large collections (400+ variables), you may need to extract in batches per collection
+- The `key` format varies: it might be `"VariableID:55:114"` or a different format depending on the Figma version
+- Always verify keys work by running the validation script (see `schemas/validation.md`)
+
+---
+
+## Usage in Scripts
+
+```js
+// Load variable by key (from registries/variables.json)
+var spMedium = await figma.variables.importVariableByKeyAsync("VariableID:55:118");
+
+// Bind to frame padding
+frame.setBoundVariable('paddingTop', spMedium);
+frame.setBoundVariable('itemSpacing', spMedium);
+
+// Bind to color fill
+var bgColor = await figma.variables.importVariableByKeyAsync("VariableID:19:114");
+frame.fills = mf(bgColor);  // using the mf() helper
+```

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

@@ -68,9 +68,22 @@ What do you want to design? (component or screen)
    ```
 
 3. **Write registries** (raw JSON, deterministic):
-   - `registries/components.json` — component names, keys, variants, properties
-   - `registries/variables.json` — variable names, keys, types, values by mode
-   - `registries/text-styles.json` — text style names, keys, font specs
+
+   **CRITICAL: Read the schema for each registry BEFORE writing it:**
+   - `schemas/components.md` → `registries/components.json` (component names, **keys**, variants, properties)
+   - `schemas/variables.md` → `registries/variables.json` (variable names, **keys**, types, values by mode)
+   - `schemas/text-styles.md` → `registries/text-styles.json` (text style names, **keys**, font specs)
+   - `schemas/assets.md` → `registries/icons.json`, `registries/logos.json`, `registries/illustrations.json` (if applicable)
+
+   All paths relative to `knowledge-base/`. The schemas contain extraction scripts and required field definitions. The `key` field is MANDATORY for every component, variable, and style entry — without it, `design` generation will fail.
+
+3b. **Validate registries (BLOCKING):**
+
+   Read `schemas/validation.md` and execute the full validation procedure:
+   1. **Structural check** — verify all registries match their schemas (every entry has `key`, correct types)
+   2. **Import test** — run validation script via `figma_execute` to test-import 3-5 sample keys per registry
+   3. **Remediation** — if ANY validation fails, re-extract the failing items using the remediation scripts
+   4. **Gate** — ALL validation checks MUST pass before proceeding to guide generation
 
 4. **Generate intelligent guides** (Claude analyzes registries and writes):
 
@@ -114,10 +127,11 @@ What do you want to design? (component or screen)
 
 7. **Validation summary:**
    ```
-   Knowledge base built:
-   - {N} components documented ({N} with variants)
-   - {N} variables ({N} colors, {N} spacing, {N} radius)
-   - {N} text styles
+   Knowledge base built and validated:
+   - {N} components documented ({N} with variants) — {N} keys verified via import test ✓
+   - {N} variables ({N} colors, {N} spacing, {N} radius) — {N} keys verified ✓
+   - {N} text styles — {N} keys verified ✓
+   - {N} asset items (icons/logos/illustrations) — {N} keys verified ✓
    - {N} layout patterns extracted from {N} screenshots
 
    Ready to design. Run: `spec {name}`

package/skills/design-workflow/references/quality-gates.md

@@ -10,6 +10,10 @@
 | Connected to Figma Desktop | Yes (before design) | Status has `setup.valid: true` |
 | DS libraries enabled | Yes (before design) | User confirmation |
 | Knowledge base exists | Yes (before spec) | `registries/` has JSON files |
+| Registry schemas followed | Yes | All registry files match schemas in `schemas/` — every entry has `key` field |
+| Registry keys validated | Yes | Sample import test passed via `figma_execute` (3-5 keys per registry) |
+| No node IDs as keys | Yes | Component entries have `key` (hex hash), NOT just `id` (node ID like `1008:174`) |
+| Variable keys present | Yes | Variables have `key` field, not just `name` paths |
 
 ---