@noemuch/bridge-ds 2.3.0 → 2.5.0

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

@@ -46,6 +46,30 @@ Without one, I'll build from scratch (slower, may need iterations).
 - Check existing specs: `specs/active/`, `specs/backlog/`
 - Check existing DS components in `references/knowledge-base/registries/components.json`
 
+### 2.5. Load Learnings
+
+Load `references/knowledge-base/learnings.json` (skip if file doesn't exist).
+
+Filter learnings by `screenType` matching the new spec's type (from step 1 context):
+- Include all **global** learnings (`scope: "global"`)
+- Include **contextual** learnings where `context.screenType` matches
+
+If matching learnings exist, include a **"Known Preferences"** section in the spec:
+
+```markdown
+## Known Preferences (from learnings)
+
+The following preferences have been learned from previous design corrections:
+
+| Rule | Property | Preferred Token | Scope | Signals |
+|------|----------|----------------|-------|---------|
+| {rule} | {property} | {to.token} | {scope} | {signals} |
+
+These preferences MUST be applied during design generation unless the spec explicitly overrides them.
+```
+
+This section goes after "Design tokens" and before "Responsive rules" (screens) or before "Acceptance criteria" (components).
+
 ### 3. Write the spec
 
 Write to `specs/active/{name}-spec.md`.

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

@@ -0,0 +1,176 @@
+# Action: sync
+
+> Incrementally sync the DS knowledge base with the current state of the Figma DS library.
+
+---
+
+## Prerequisites
+
+- Knowledge base exists (`references/knowledge-base/registries/` has JSON files) — abort if missing: "No knowledge base found. Run: `setup` first."
+- Figma MCP transport available (console: `figma_get_status`, official: `whoami` — see `references/transport-adapter.md` Section F)
+
+---
+
+## Procedure
+
+### 1. Read current registries
+
+Load all existing registries:
+- `registries/components.json`
+- `registries/variables.json`
+- `registries/text-styles.json`
+- `registries/icons.json` (if exists)
+- `registries/logos.json` (if exists)
+- `registries/illustrations.json` (if exists)
+
+Note the `meta.fileKey` from any registry to identify the DS source file.
+
+### 2. Re-extract from Figma
+
+Use the same MCP tools as `setup` (tool names depend on transport — see `references/transport-adapter.md`):
+
+**Console transport:**
+- `figma_get_design_system_kit({ file_key })` → full DS snapshot
+- `figma_get_variables({ file_key })` → current variables
+- `figma_get_styles({ file_key })` → current text/color/effect styles
+- If keys missing, supplement with `figma_execute` extraction scripts (from `schemas/`)
+
+**Official transport** (composite strategy — see transport-adapter.md Section D):
+- `get_variable_defs({ fileKey })` → variables
+- `search_design_system({ query: "*", includeComponents: true })` → components
+- `search_design_system({ query: "*", includeStyles: true })` → styles
+- Supplement with `use_figma` extraction scripts from schemas as needed
+
+### 3. Diff registries
+
+Compare old vs new for each registry:
+
+**Components (`components.json`):**
+- **Added:** components in new extraction not in current registry
+- **Removed:** components in current registry not in new extraction (match by `key`)
+- **Modified:** same `key` but different `properties`, `name`, or `variants` count
+
+**Variables (`variables.json`):**
+- **Added:** new variable keys
+- **Removed:** variable keys no longer present
+- **Modified:** same `key` but different `name`, `valuesByMode`, or collection assignment
+
+**Text styles (`text-styles.json`):**
+- **Added:** new style keys
+- **Removed:** style keys no longer present
+- **Modified:** same `key` but different `name` or font properties
+
+**Assets (icons/logos/illustrations):**
+- Same add/remove/modify logic by `key`
+
+### 4. Impact analysis
+
+For removed or modified items, check references across the knowledge base:
+
+**Guides impact:**
+- Search `guides/components/*.md` for references to removed/renamed components
+- Search `guides/tokens/*.md` for references to removed/renamed variables
+- Search `guides/patterns/*.md` for affected patterns
+
+**Learnings impact:**
+- Check `learnings.json` for learnings referencing removed tokens
+- Flag affected learnings (don't delete — mark for user review)
+
+**Active specs impact:**
+- Check `specs/active/*.md` for references to removed/modified components or tokens
+
+### 5. Report to user
+
+Present the diff report BEFORE applying changes:
+
+```markdown
+## DS Sync Report
+
+### Summary
+- Components: +{added} ~{modified} -{removed}
+- Variables: +{added} ~{modified} -{removed}
+- Text styles: +{added} ~{modified} -{removed}
+- Assets: +{added} ~{modified} -{removed}
+
+### Added
+{list of new items per registry}
+
+### Modified
+{list of changed items with old → new values}
+
+### Removed (⚠️ Breaking Changes)
+{list of removed items}
+
+#### Impact of removals:
+- Guides affected: {list of guide files referencing removed items}
+- Learnings affected: {list of learning IDs referencing removed tokens}
+- Active specs affected: {list of spec files referencing removed items}
+
+### Recommended actions:
+1. {action per breaking change}
+```
+
+**BLOCKING:** If there are removals (breaking changes), ask the user to confirm before proceeding:
+```
+{n} items were removed from the DS. This affects {n} guides and {n} learnings.
+Proceed with sync? (Removed items will be deleted from registries, affected guides will be patched.)
+```
+
+### 6. Apply updates
+
+After user confirmation:
+
+**Update registries:**
+- Add new entries
+- Update modified entries (preserve `key`, update other fields)
+- Remove deleted entries
+
+**Patch guides:**
+- For removed components: remove or comment out references in affected guide files
+- For renamed components: find-and-replace old name with new name
+- For modified properties: update property descriptions in component guides
+
+**Update learnings:**
+- For learnings referencing removed tokens: add a flag entry noting the token was removed
+- Do NOT delete learnings — they may still be conceptually valid even if the token name changed
+
+**Re-validate registries:**
+- Run sample import test (3-5 keys per registry) via `figma_execute` to confirm new/modified keys work
+- Follow `schemas/validation.md` procedure
+
+### 7. Regenerate affected guides (optional)
+
+If significant changes detected (>10 items changed or any category restructured), suggest:
+```
+Significant DS changes detected. Regenerate affected guides?
+- Token guides: {list if token changes}
+- Component guides: {list if component changes}
+```
+
+Only regenerate if user confirms. Use the same guide generation logic as `setup`.
+
+---
+
+## Output
+
+```
+DS Sync complete.
+
+Updated:
+  - components.json: +{n} ~{n} -{n}
+  - variables.json: +{n} ~{n} -{n}
+  - text-styles.json: +{n} ~{n} -{n}
+  - {assets}: +{n} ~{n} -{n}
+
+Guides patched: {n} files
+Learnings preserved: {n} ({n} flagged for review)
+Validation: {PASS/FAIL}
+
+Next: Review updated registries, then continue with `spec` or `design`.
+```
+
+---
+
+## Transition
+
+After sync → suggest: "DS synced. Run: `status` to see current state."

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

@@ -499,6 +499,22 @@ Input (default)        → components.json key: def456  → import ✓
 
 ---
 
+## Rule 23: Transport-aware scripting
+
+Script format depends on the active MCP transport. See `references/transport-adapter.md` for full details.
+
+| Aspect | Console (`figma_execute`) | Official (`use_figma`) |
+|--------|--------------------------|------------------------|
+| Wrapper | IIFE: `return (async function() { ... })();` | Top-level `await`, no IIFE |
+| Parameters | `{ code }` | `{ fileKey, description, code }` |
+| `figma.notify()` | Allowed | **Forbidden** |
+| `getPluginData()` | Allowed | **Forbidden** (use `getSharedPluginData()`) |
+| Response size | Unlimited | **20KB limit** — chunk large extractions |
+
+**Before writing any script, check which transport is active and use the correct format.**
+
+---
+
 ## Standard Script Boilerplate
 
 ```js
@@ -550,3 +566,50 @@ return (async function() {
   return { success: true };
 })();
 ```
+
+### Official transport version (use_figma)
+
+Same helpers, no IIFE wrapper. Called with `use_figma({ fileKey: "...", description: "...", code: "..." })`.
+
+```js
+  // ─── FONTS ───
+  await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+  await figma.loadFontAsync({ family: "Inter", style: "Medium" });
+  await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
+  await figma.loadFontAsync({ family: "Inter", style: "Bold" });
+
+  // ─── VARIABLES (from registries/variables.json) ───
+  // var spLarge = await figma.variables.importVariableByKeyAsync("YOUR_KEY");
+
+  // ─── HELPERS ───
+  function mf(colorVar) {
+    var p = figma.util.solidPaint("#000000");
+    p = figma.variables.setBoundVariableForPaint(p, "color", colorVar);
+    return [p];
+  }
+
+  function appendFill(parent, child, fillH, fillV) {
+    parent.appendChild(child);
+    if (fillH) child.layoutSizingHorizontal = "FILL";
+    if (fillV) child.layoutSizingVertical = "FILL";
+  }
+
+  function bindPadding(frame, top, right, bottom, left) {
+    if (top) frame.setBoundVariable("paddingTop", top);
+    if (right) frame.setBoundVariable("paddingRight", right);
+    if (bottom) frame.setBoundVariable("paddingBottom", bottom);
+    if (left) frame.setBoundVariable("paddingLeft", left);
+  }
+
+  function bindRadius(frame, radiusVar) {
+    frame.setBoundVariable("topLeftRadius", radiusVar);
+    frame.setBoundVariable("topRightRadius", radiusVar);
+    frame.setBoundVariable("bottomLeftRadius", radiusVar);
+    frame.setBoundVariable("bottomRightRadius", radiusVar);
+  }
+
+  // ─── BUILD ───
+  // ... your design code here ...
+
+  return { success: true };
+```

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

@@ -43,6 +43,8 @@ knowledge-base/
   ui-references/                 ← Product screenshots for pattern extraction
     screenshots/                 ← PNG/JPG files of your product's key screens
     ui-references-guide.md       ← Which screenshot for which pattern type
+
+  learnings.json                 ← Persistent learning store (generated by `learn`)
 ```
 
 ## How to populate
@@ -56,6 +58,21 @@ Run `/design-workflow setup` in Claude Code. Claude will:
 5. **Ask for screenshots** of your product's key screens
 6. **Generate** layout pattern documentation from the screenshots
 
+## Learnings
+
+`learnings.json` stores user corrections detected by the `learn` action. See `schemas/learnings.md` for the full schema.
+
+- **Learnings** = DS-compliant changes (user swapped one token for another) → applied in future generations
+- **Flags** = non-DS-compliant changes (hardcoded hex, raw values) → surfaced for user review
+- Learnings start as `contextual` (screen/component-specific) and promote to `global` after 3+ signals across 2+ screen types
+
 ## How to update
 
-When your DS evolves (new components, changed tokens), run `/design-workflow setup` again. Claude will detect existing registries and offer to update them incrementally.
+When your DS evolves (new components, changed tokens), run `/design-workflow sync` for an incremental update. Claude will:
+
+1. Re-extract the DS from Figma
+2. Diff against existing registries
+3. Show a report: added, modified, removed items
+4. Apply updates after confirmation (with breaking change analysis)
+
+For a full re-extraction, run `/design-workflow setup` again.

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

@@ -142,3 +142,9 @@ var logoInstance = defaultVariant.createInstance();
 - 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`)
+
+---
+
+## Transport Note
+
+For official transport: remove the IIFE wrapper from extraction scripts, add `fileKey` and `description` to the `use_figma` call. See `references/transport-adapter.md` for details.

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

@@ -122,3 +122,9 @@ Group components by semantic category:
 - `indicators` — Avatars, Status, Progress
 
 Use whatever categories match the DS's own organization.
+
+---
+
+## Transport Note
+
+For official transport: remove the IIFE wrapper from extraction scripts, add `fileKey` and `description` to the `use_figma` call. See `references/transport-adapter.md` for details.

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

@@ -0,0 +1,250 @@
+# Schema: learnings.json
+
+> **Read this BEFORE writing or updating learnings.json.**
+
+---
+
+## Purpose
+
+`learnings.json` stores corrections the user makes to generated designs. When Bridge generates a design and the user manually fixes it in Figma, the `learn` action extracts those changes and persists them here. Future generations consult these learnings to avoid repeating the same mistakes.
+
+---
+
+## Required Structure
+
+```json
+{
+  "meta": {
+    "version": "1.0",
+    "lastUpdated": "YYYY-MM-DD"
+  },
+  "learnings": [
+    {
+      "id": "l-YYYYMMDD-NNN",
+      "scope": "contextual",
+      "context": {
+        "screenType": "settings",
+        "component": "card",
+        "section": "content"
+      },
+      "change": {
+        "property": "itemSpacing",
+        "from": { "token": "spacing/large", "value": 24 },
+        "to": { "token": "spacing/medium", "value": 16 }
+      },
+      "rule": "For settings screens, cards use spacing/medium (not large).",
+      "signals": 1,
+      "history": [
+        { "date": "2026-03-20", "spec": "settings-screen" }
+      ]
+    }
+  ],
+  "flags": [
+    {
+      "id": "f-YYYYMMDD-NNN",
+      "spec": "settings-screen",
+      "description": "Hardcoded hex #FF5722 on node 'StatusBadge'",
+      "resolved": false
+    }
+  ]
+}
+```
+
+---
+
+## Field Requirements
+
+### Top-level
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `meta.version` | **YES** | Schema version (`"1.0"`) |
+| `meta.lastUpdated` | **YES** | ISO date of last modification |
+| `learnings` | **YES** | Array of DS-compliant changes detected (can be empty) |
+| `flags` | **YES** | Array of non-DS-compliant changes that need user attention (can be empty) |
+
+### Learning entry
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | **YES** | Unique ID: `l-YYYYMMDD-NNN` |
+| `scope` | **YES** | `"contextual"` (screen/component-specific) or `"global"` (applies everywhere) |
+| `context` | **YES** | Where this learning applies: `screenType`, `component`, `section` (all optional strings) |
+| `change` | **YES** | What changed: `property`, `from` (token + value), `to` (token + value) |
+| `change.property` | **YES** | Figma property name (e.g., `itemSpacing`, `fills`, `cornerRadius`) |
+| `change.from` | **YES** | Original value: `{ "token": "...", "value": ... }` — token may be null if raw |
+| `change.to` | **YES** | Corrected value: `{ "token": "...", "value": ... }` |
+| `rule` | **YES** | Human-readable rule derived from the change |
+| `signals` | **YES** | Number of times this correction has been observed |
+| `history` | **YES** | Array of `{ "date", "spec" }` entries tracking each observation |
+
+### Flag entry
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | **YES** | Unique ID: `f-YYYYMMDD-NNN` |
+| `spec` | **YES** | Which spec triggered this flag |
+| `description` | **YES** | What was changed and why it's flagged (e.g., hardcoded hex) |
+| `resolved` | **YES** | `false` until user addresses it |
+
+---
+
+## Scope Promotion Rules
+
+A learning starts as `"contextual"` and can be promoted to `"global"`:
+
+1. **Threshold:** `signals >= 3` AND observations come from at least 2 different `screenType` values
+2. **Contradiction check:** If the same `property` has learnings pointing to different `to` tokens → do NOT promote. Instead, flag for user review.
+3. **On promotion:** Change `scope` to `"global"`, keep `context` for reference but it no longer restricts matching.
+
+---
+
+## Snapshot Structure
+
+Snapshots are saved after design generation to enable diffing during `learn`.
+
+**File:** `specs/active/{name}-snapshot.json`
+
+```json
+{
+  "meta": {
+    "spec": "settings-screen",
+    "generatedAt": "YYYY-MM-DDTHH:mm:ss",
+    "rootNodeId": "123:456",
+    "fileKey": "abc123"
+  },
+  "tree": {
+    "id": "123:456",
+    "name": "Settings Screen",
+    "type": "FRAME",
+    "width": 1440,
+    "height": 900,
+    "layoutMode": "VERTICAL",
+    "primaryAxisAlignItems": "MIN",
+    "counterAxisAlignItems": "MIN",
+    "itemSpacing": 0,
+    "paddingTop": 0,
+    "paddingBottom": 0,
+    "paddingLeft": 0,
+    "paddingRight": 0,
+    "cornerRadius": 0,
+    "boundVariables": {
+      "itemSpacing": "spacing/large"
+    },
+    "fills": [
+      { "type": "SOLID", "color": "#F5F5F5", "boundVariable": "color/background/neutral/default" }
+    ],
+    "componentKey": null,
+    "componentName": null,
+    "children": []
+  }
+}
+```
+
+### Node tree extraction script
+
+Use this via `figma_execute` to extract the snapshot tree (max depth 10):
+
+```js
+return (async function() {
+  var root = await figma.getNodeByIdAsync("ROOT_NODE_ID");
+  if (!root) return { error: "Node not found" };
+
+  function extractNode(node, depth) {
+    if (depth > 10) return null;
+    var data = {
+      id: node.id,
+      name: node.name,
+      type: node.type,
+      width: Math.round(node.width),
+      height: Math.round(node.height)
+    };
+    if (node.layoutMode) {
+      data.layoutMode = node.layoutMode;
+      data.primaryAxisAlignItems = node.primaryAxisAlignItems;
+      data.counterAxisAlignItems = node.counterAxisAlignItems;
+      data.itemSpacing = node.itemSpacing;
+      data.paddingTop = node.paddingTop;
+      data.paddingBottom = node.paddingBottom;
+      data.paddingLeft = node.paddingLeft;
+      data.paddingRight = node.paddingRight;
+    }
+    if (node.cornerRadius !== undefined) data.cornerRadius = node.cornerRadius;
+    // Bound variables
+    var bv = {};
+    try {
+      var bindings = node.boundVariables || {};
+      for (var prop in bindings) {
+        var b = bindings[prop];
+        if (b && b.id) bv[prop] = b.id;
+        else if (Array.isArray(b)) bv[prop] = b.map(function(x) { return x.id; });
+      }
+    } catch(e) {}
+    if (Object.keys(bv).length > 0) data.boundVariables = bv;
+    // Fills
+    if (node.fills && node.fills.length > 0) {
+      data.fills = node.fills.map(function(f) {
+        var fill = { type: f.type };
+        if (f.color) fill.color = "#" +
+          Math.round(f.color.r*255).toString(16).padStart(2,"0") +
+          Math.round(f.color.g*255).toString(16).padStart(2,"0") +
+          Math.round(f.color.b*255).toString(16).padStart(2,"0");
+        return fill;
+      });
+    }
+    // Component info
+    if (node.type === "INSTANCE") {
+      data.componentKey = node.mainComponent ? node.mainComponent.key : null;
+      data.componentName = node.mainComponent ? node.mainComponent.name : null;
+    }
+    // Children
+    if (node.children && node.children.length > 0) {
+      data.children = [];
+      for (var i = 0; i < node.children.length; i++) {
+        var child = extractNode(node.children[i], depth + 1);
+        if (child) data.children.push(child);
+      }
+    }
+    return data;
+  }
+
+  return { tree: extractNode(root, 0) };
+})();
+```
+
+---
+
+## How Learnings Are Used
+
+### During `spec` (Step 2.5)
+
+Load `learnings.json`, filter by `screenType` matching the new spec's type. Display matching learnings as **"Known Preferences"** in the spec output.
+
+### During `design` (Step 1e)
+
+After pattern matching and before generation, load `learnings.json` and filter:
+- **Global learnings:** Always apply
+- **Contextual learnings:** Match by `screenType`, `component`, or `section`
+
+List applicable learnings in the pre-script audit and integrate into generation scripts.
+
+### During `done`
+
+Persist any learnings from the current `learn` session. Clean up the snapshot file.
+
+---
+
+## File Location
+
+```
+knowledge-base/
+  learnings.json          ← Persistent learning store
+specs/active/
+  {name}-snapshot.json    ← Temporary snapshot (deleted after done)
+```
+
+---
+
+## Transport Note
+
+For official transport: remove the IIFE wrapper from the node tree extraction script, add `fileKey` and `description` to the `use_figma` call. See `references/transport-adapter.md` for details.

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

@@ -115,3 +115,9 @@ Group text styles by their first path segment:
 - `code` — Monospace / code text
 
 Weight/emphasis variants are the second segment: `regular`, `accent`, `emphasis`, `bold`.
+
+---
+
+## Transport Note
+
+For official transport: remove the IIFE wrapper from extraction scripts, add `fileKey` and `description` to the `use_figma` call. See `references/transport-adapter.md` for details.

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

@@ -180,3 +180,9 @@ 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
+
+---
+
+## Transport Note
+
+For official transport: remove the IIFE wrapper from extraction and validation scripts, add `fileKey` and `description` to the `use_figma` call. See `references/transport-adapter.md` for details.

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

@@ -151,3 +151,9 @@ frame.setBoundVariable('itemSpacing', spMedium);
 var bgColor = await figma.variables.importVariableByKeyAsync("VariableID:19:114");
 frame.fills = mf(bgColor);  // using the mf() helper
 ```
+
+---
+
+## Transport Note
+
+For official transport: remove the IIFE wrapper from extraction scripts, add `fileKey` and `description` to the `use_figma` call. See `references/transport-adapter.md` for details.