@noemuch/bridge-ds 2.1.0 → 2.3.0

package/lib/cli.js

@@ -1,5 +1,5 @@
 const path = require('path');
-const { scaffold } = require('./scaffold');
+const { scaffold, update } = require('./scaffold');
 const { checkMcp, setupMcp } = require('./mcp-setup');
 
 // ── Branding ──────────────────────────────────────────────
@@ -113,6 +113,35 @@ async function cmdInit() {
   print('');
 }
 
+async function cmdUpdate() {
+  banner();
+  header('Updating Bridge DS skill files');
+
+  const cwd = process.cwd();
+
+  step(1, 2, 'Updating skill files');
+  const spinner = new Spinner('Updating SKILL.md, actions, rules, schemas, templates...').start();
+  const result = update(cwd);
+
+  if (result.error) {
+    spinner.stop();
+    error(result.error);
+    process.exit(1);
+  }
+
+  spinner.stop(`${result.updated.length} files updated`);
+
+  for (const f of result.updated) {
+    muted(f);
+  }
+
+  step(2, 2, 'Done!');
+  print('');
+  success('Skill files updated. Your knowledge base (registries, guides) was preserved.');
+  info('No need to re-run /design-workflow setup.');
+  print('');
+}
+
 function cmdHelp() {
   banner();
   print(`${C.bold}  Commands:${C.reset}`);
@@ -120,13 +149,17 @@ function cmdHelp() {
   print(`    ${C.orange}init${C.reset}       Initialize Bridge DS in current project`);
   print(`               Scaffolds skills, commands, and specs directories`);
   print('');
+  print(`    ${C.orange}update${C.reset}     Update skill files to latest version`);
+  print(`               Preserves your knowledge base (registries, guides)`);
+  print('');
   print(`    ${C.orange}help${C.reset}       Show this help message`);
   print(`    ${C.orange}version${C.reset}    Show version`);
   print('');
   print(`${C.bold}  Usage:${C.reset}`);
   print('');
-  print(`    ${C.dim}npx bridge-ds init${C.reset}     # Initialize in current project`);
-  print(`    ${C.dim}bridge-ds help${C.reset}          # Show help`);
+  print(`    ${C.dim}npx @noemuch/bridge-ds init${C.reset}     # Initialize in current project`);
+  print(`    ${C.dim}npx @noemuch/bridge-ds update${C.reset}   # Update skill files only`);
+  print(`    ${C.dim}bridge-ds help${C.reset}                  # Show help`);
   print('');
   print(`${C.bold}  After init:${C.reset}`);
   print('');
@@ -152,6 +185,9 @@ async function run(args) {
     case 'init':
       await cmdInit();
       break;
+    case 'update':
+      await cmdUpdate();
+      break;
     case 'help':
     case '--help':
     case '-h':

package/lib/scaffold.js

@@ -3,8 +3,9 @@ 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) {
+function copyDir(src, dest, skipDirs = []) {
   const created = [];
   if (!fs.existsSync(dest)) {
     fs.mkdirSync(dest, { recursive: true });
@@ -13,7 +14,8 @@ function copyDir(src, dest) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
     if (entry.isDirectory()) {
-      created.push(...copyDir(srcPath, destPath));
+      if (skipDirs.includes(entry.name)) continue;
+      created.push(...copyDir(srcPath, destPath, skipDirs));
     } else {
       fs.copyFileSync(srcPath, destPath);
       created.push(destPath);
@@ -117,4 +119,37 @@ function scaffold(projectDir) {
   return { created };
 }
 
-module.exports = { scaffold };
+/**
+ * Update only the skill files (SKILL.md, actions, rules, schemas, templates).
+ * Preserves all user-generated data (registries, guides, ui-references, specs).
+ * Returns { updated: string[] } with relative paths of updated files.
+ */
+function update(projectDir) {
+  const updated = [];
+  const pkgRoot = path.resolve(__dirname, '..');
+
+  const skillsSrc = path.join(pkgRoot, 'skills', 'design-workflow');
+  const skillsDest = path.join(projectDir, '.claude', 'skills', 'design-workflow');
+
+  if (!fs.existsSync(skillsDest)) {
+    return { updated: [], error: 'Bridge DS not initialized. Run: npx @noemuch/bridge-ds init' };
+  }
+
+  // Copy skill files, skipping user-generated KB data
+  const userDataDirs = ['registries', 'guides', 'ui-references'];
+  const files = copyDir(skillsSrc, skillsDest, userDataDirs);
+  updated.push(...files.map(f => path.relative(projectDir, f)));
+
+  // Update command file
+  const cmdSrc = path.join(pkgRoot, 'commands', 'design-workflow.md');
+  const cmdDest = path.join(projectDir, '.claude', 'commands', 'design-workflow.md');
+  if (fs.existsSync(cmdSrc)) {
+    fs.mkdirSync(path.dirname(cmdDest), { recursive: true });
+    fs.copyFileSync(cmdSrc, cmdDest);
+    updated.push(path.relative(projectDir, cmdDest));
+  }
+
+  return { updated };
+}
+
+module.exports = { scaffold, update };

package/package.json

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