@noemuch/bridge-ds 2.2.0 → 2.3.0

package/package.json

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

@@ -69,7 +69,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** via `figma_take_screenshot({ node_id, file_key })`
+2. **Inspect the reference structure** via `figma_execute` — 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

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

@@ -12,6 +12,17 @@ Ask or infer from context:
 - **Component**: design system primitive, block, or composition (Button, Card, Tag...)
 - **Screen**: full interface or page (dashboard, settings, onboarding flow...)
 
+**If screen mode detected**, immediately ask the user:
+```
+This is a screen spec. For reliable generation, I need a reference:
+
+→ Do you have a Figma URL of an existing screen with a similar layout?
+  (e.g., same sidebar + content structure, same navigation shell)
+
+With a reference, I'll clone the shell and replace the content (fast, accurate).
+Without one, I'll build from scratch (slower, may need iterations).
+```
+
 ### 2. Gather context
 
 - **Load design patterns** (MANDATORY for screens, recommended for components):
@@ -95,6 +106,29 @@ For each UI pattern described in the spec, check if it exists in `registries/com
 - A navigation pattern not covered by existing nav components
 - A data display pattern not covered by existing list/table components
 
+### 3c. Auto-enrich DS Components Used (screen mode)
+
+For every component listed in "DS Components Used", resolve the exact registry key:
+
+1. Search `registries/components.json` by name → fill the `Key` column with the exact key
+2. Search `registries/icons.json`, `registries/logos.json` if applicable
+3. For each element, determine the **strategy**:
+   - Found in registry → `import`
+   - Not in registry but exists in reference screen → `clone` (note the reference node ID)
+   - Not in registry and no reference → flag as "New DS Component Required"
+
+**Example enriched table:**
+```
+| Component | Variant | Key / Source | Strategy |
+|-----------|---------|-------------|----------|
+| Button | primary, large | components.json → key: abc123 | import |
+| Logo | finary-one | logos.json → key: 78defbf4 | import |
+| SideStepper | 5 steps | components.json → key: 1668b598 | clone (reference 9569:40240) |
+| ProductBackground | finaryOne | NOT IN REGISTRY | clone (reference 9569:40233) |
+```
+
+This removes ambiguity at design time and prevents wrong component selection.
+
 ### 4. Validate
 
 **Token architecture:**

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

@@ -446,6 +446,59 @@ Same applies to `setFillStyleIdAsync`, `setStrokeStyleIdAsync`, `setEffectStyleI
 
 ---
 
+## Rule 22: Clone-first for screens with reference
+
+When a reference Figma node is available (from the spec's "Reference Screen" section), **clone the shell structure instead of rebuilding from scratch**.
+
+### When to clone
+
+Clone when the element is:
+- A **layout shell** (sidebar + content + footer structure)
+- A **complex pre-configured instance** (stepper with labels, navigation with active states)
+- A **local/unpublished component** (backgrounds, decorative elements not in the DS library)
+- An instance with **deeply nested properties** (3+ levels, properties on nested children not exposed at root)
+
+### How to clone
+
+```js
+// Clone an entire subtree from a reference node
+var ref = await figma.getNodeByIdAsync("REFERENCE_NODE_ID");
+var clone = ref.clone();
+
+// Position the clone
+clone.x = 0;
+clone.y = 0;
+
+// Now modify the clone's content (replace text, swap instances, etc.)
+var title = clone.findOne(function(n) { return n.name === "title" && n.type === "TEXT"; });
+if (title) title.characters = "New Title";
+```
+
+### Clone vs Import decision
+
+| Situation | Strategy |
+|-----------|----------|
+| Component in DS library, simple props | **Import** via `importComponentByKeyAsync` |
+| Component in DS library, deeply nested | **Clone** from reference if available |
+| Local/unpublished component | **Clone** from reference (only option) |
+| Layout shell (sidebar + content + footer) | **Clone** the whole shell, replace content |
+| Pre-configured stepper/nav with labels set | **Clone** (API can't easily override nested props) |
+
+### Pre-script audit format for clone elements
+
+```
+PRE-SCRIPT AUDIT — Step {n}:
+Spec requires:           Source:                      Strategy:
+─────────────────────────────────────────────────────────────────
+Sidebar shell          → reference node 9569:40232    → clone ✓
+ProductBackground      → reference node 9569:40233    → clone ✓
+SideStepper (5 steps)  → reference node 9569:40240    → clone + modify labels ✓
+Button (primary)       → components.json key: abc123  → import ✓
+Input (default)        → components.json key: def456  → import ✓
+```
+
+---
+
 ## Standard Script Boilerplate
 
 ```js

package/skills/design-workflow/references/templates/screen-template.md

@@ -8,6 +8,23 @@
 
 ---
 
+## Reference Screen (REQUIRED)
+
+> A screen that already exists in Figma with the same layout shell (sidebar + content, topbar + main, etc.).
+> Claude will clone the shell from this reference and replace the content.
+> **Without a reference, generation is significantly less reliable.**
+
+| | |
+|---|---|
+| **Reference URL** | {Figma URL of an existing screen with the same shell/layout} |
+| **Reference node ID** | {nodeId extracted from URL} |
+| **Shell elements to clone** | {list: e.g., "sidebar frame, product background, stepper, footer"} |
+| **What changes vs reference** | {what content/sections differ from the reference} |
+
+> If no existing screen uses this layout: write "None — new layout, building from scratch" and document the shell structure in detail in Layout Structure below.
+
+---
+
 ## Visual Reference
 
 > Identifies which design pattern this screen follows.
@@ -67,10 +84,15 @@
 
 > Look up component keys in `knowledge-base/registries/components.json`.
 > Use `knowledge-base/guides/components/overview.md` decision tree to choose the right component.
+> Mark each element as `import` (from DS library) or `clone` (from reference screen).
+
+| Component | Variant/Size | Key / Source | Strategy | Location |
+|-----------|-------------|-------------|----------|----------|
+| `{Name}` | {variant} | {registry key or "reference node {id}"} | import / clone | {section} |
 
-| Component | Variant/Size | Figma Key | Location |
-|-----------|-------------|-----------|----------|
-| `{Name}` | {variant} | {key from registry} | {section} |
+**Strategy guide:**
+- `import` — Component exists in DS library → use `importComponentByKeyAsync(key)`
+- `clone` — Component is local/unpublished or pre-configured in reference → clone from reference node
 
 ---