@noemuch/bridge-ds 2.0.0 → 2.0.1

package/package.json

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

@@ -109,14 +109,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 20
 ```
 
-**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,22 @@ mainComponent.y = 400;
 
 ---
 
+## Rule 20: 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