@noemuch/bridge-ds 2.3.0 → 2.5.1

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.

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

@@ -34,13 +34,31 @@ STEP 6  Done (archive + retro)
 
 **Trigger**: any design-related request (spec, design, new component, new screen, setup, etc.)
 
-### 0a. Check figma-console-mcp
+### 0a. Check Figma MCP Transport
 
-| Check | How to verify | Block message if fail |
-|-------|--------------|----------------------|
-| figma-console-mcp available | Call `figma_get_status()` — should return connection info | "figma-console-mcp is not configured. Run: `claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN -- npx -y figma-console-mcp@latest`" |
-| Connected to Figma | `figma_get_status()` returns `setup.valid: true` | "Figma Desktop is not connected. Open your Figma file → Plugins → Development → Run the Desktop Bridge plugin." |
-| DS libraries enabled | Ask user to confirm | "Make sure your DS libraries are enabled in the target Figma file (Assets panel → Team → Enable). Confirm when done." |
+Detect which transport is available (see `references/transport-adapter.md` Section A):
+
+1. **Check console transport:** Is `figma_execute` available? Try `figma_get_status()`.
+2. **Check official transport:** Is `use_figma` available? Try `whoami()`.
+
+| Result | Action |
+|--------|--------|
+| Console available | Use console transport. Verify: `figma_get_status()` returns `setup.valid: true` |
+| Official only | Use official transport. Verify: `whoami()` succeeds, then test `use_figma` call |
+| Both available | Use console (preferred — more capable, no response limits) |
+| Neither available | **Block.** Show setup instructions for both options (see transport-adapter.md Section A) |
+
+**Post-detection checks:**
+
+| Check | Console | Official | Block message if fail |
+|-------|---------|----------|-----------------------|
+| Transport connected | `figma_get_status()` → `setup.valid: true` | `whoami()` succeeds + test `use_figma` call | Console: "Figma Desktop is not connected. Open: Plugins → Development → Desktop Bridge." / Official: "Figma MCP not authenticated. Check your Figma MCP configuration." |
+| DS libraries enabled | Ask user to confirm | Ask user to confirm | "Make sure your DS libraries are enabled in the target Figma file (Assets panel → Team → Enable). Confirm when done." |
+
+Report the active transport:
+```
+Transport: {console | official} ✓
+```
 
 **Note:** Setup check can be deferred to just before STEP 4 (design) if the user only wants to write a spec first. But it MUST pass before any Figma generation.
 
@@ -56,17 +74,41 @@ What do you want to design? (component or screen)
 
 **If knowledge base is empty → build it:**
 
+#### Knowledge Base Directory Selection
+
+Determine where to create the knowledge base:
+- If `./.claude/skills/design-workflow/references/knowledge-base/` already exists (npm scaffold mode) → use that path
+- Otherwise (plugin mode or fresh project) → create and use `./bridge-ds/knowledge-base/`
+
+Create these subdirectories in the chosen KB root:
+- `registries/`
+- `guides/tokens/`
+- `guides/components/`
+- `guides/patterns/`
+- `guides/assets/`
+- `ui-references/screenshots/`
+
 #### KB Generation Flow
 
 1. **Ask the user for the DS library file key/URL** (the Figma file containing their design system)
 
 2. **Extract raw data via MCP tools:**
+
+   **Console transport:**
    ```
    figma_get_design_system_kit({ file_key: "...", format: "full" })
    figma_get_variables({ file_key: "..." })
    figma_get_styles({ file_key: "..." })
    ```
 
+   **Official transport** (no `figma_get_design_system_kit`): Use the composite strategy from `references/transport-adapter.md` Section D:
+   ```
+   get_variable_defs({ fileKey: "..." })
+   search_design_system({ query: "*", includeComponents: true })
+   search_design_system({ query: "*", includeStyles: true })
+   ```
+   Supplement with `use_figma` extraction scripts from the schemas as needed.
+
 3. **Write registries** (raw JSON, deterministic):
 
    **CRITICAL: Read the schema for each registry BEFORE writing it:**
@@ -278,7 +320,7 @@ Now we can design the screen with real DS components.
 **Prerequisites (ALL must pass):**
 - [ ] Spec validated (STEP 2 passed)
 - [ ] New components created if needed (STEP 3 passed)
-- [ ] figma-console-mcp connected (STEP 0 check)
+- [ ] Figma MCP transport connected (STEP 0 check)
 - [ ] DS libraries enabled
 
 **If any prerequisite fails → block with specific message from Block Messages Reference.**
@@ -344,8 +386,8 @@ Ready for the next design!
 
 | Situation | Message |
 |-----------|---------|
-| No MCP server | "figma-console-mcp is not configured. Run: `claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN -- npx -y figma-console-mcp@latest`" |
-| Not connected | "Figma Desktop is not connected. Open: Plugins → Development → Desktop Bridge." |
+| No MCP transport | "No Figma MCP transport detected. See `references/transport-adapter.md` Section A for setup instructions (console or official)." |
+| Not connected | Console: "Figma Desktop is not connected. Open: Plugins → Development → Desktop Bridge." / Official: "Figma MCP not authenticated. Check your configuration." |
 | Libraries not enabled | "Enable your DS libraries in the target Figma file: Assets → Team → Enable." |
 | No knowledge base | "Knowledge base not built yet. Run: `setup`" |
 | No active spec | "No active spec. Let's create one: component or screen?" |

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

@@ -6,8 +6,8 @@
 
 | Gate | Blocking | Check |
 |------|----------|-------|
-| figma-console-mcp available | Yes (before design) | `figma_get_status()` returns valid connection |
-| Connected to Figma Desktop | Yes (before design) | Status has `setup.valid: true` |
+| Figma MCP transport available | Yes (before design) | Console: `figma_get_status()` returns valid connection / Official: `whoami()` succeeds (see transport-adapter.md Section F) |
+| Connected to Figma | Yes (before design) | Console: `setup.valid: true` / Official: `whoami()` + test `use_figma` call |
 | 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 |
@@ -121,6 +121,33 @@
 
 ---
 
+## Phase: learn (after design corrections)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| Active spec exists | Yes | `specs/active/{name}-spec.md` present |
+| Snapshot exists | Yes | `specs/active/{name}-snapshot.json` present |
+| Figma MCP transport available | Yes | Console: `figma_get_status()` / Official: `whoami()` (see transport-adapter.md) |
+| Root node still exists | Yes | Plugin API execution can find the node from snapshot meta |
+| Changes classified | Yes | Every change classified as LEARNING or FLAG |
+| Learnings have valid tokens | Yes | Every LEARNING references a token from `registries/variables.json` |
+| Flags surfaced to user | Yes | All FLAG items reported before saving |
+
+---
+
+## Phase: sync (DS incremental update)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| Knowledge base exists | Yes | `registries/` has JSON files |
+| Figma MCP transport available | Yes | Console: `figma_get_status()` / Official: `whoami()` (see transport-adapter.md) |
+| Diff computed before apply | Yes | Report shown to user before any registry modification |
+| Breaking changes confirmed | Yes (if removals) | User explicitly approves deletion of removed items |
+| Registry validation after update | Yes | Sample import test passes (3-5 keys per registry) |
+| Guides patched for removals | Yes (if removals) | No guide references deleted components/tokens |
+
+---
+
 ## Skip Policy
 
 - **Non-skippable (NEVER):** spec creation, spec validation, new components check, pattern matching, visual fidelity review, DS component reuse audit (Rule 18), pre-script element audit, registry loading
@@ -129,3 +156,25 @@
   1. Warn user about quality impact
   2. Log the skip reason
   3. Flag in review as advisory issue
+
+---
+
+## Phase: Quick Mode
+
+Quick mode relaxes some gates while keeping critical ones:
+
+### Relaxed (non-blocking in quick mode)
+- Pattern matching: best-effort, not blocking
+- Spec creation and validation: skipped entirely
+- New components check: skipped (use what exists in registries)
+- Formal review: skipped (user can run separately)
+- Acceptance criteria: none (no spec)
+
+### Still enforced (BLOCKING even in quick mode)
+- Pre-script element audit (Rule 18) — every element must be in registries
+- Zero hardcoded hex colors — all colors via setBoundVariableForPaint
+- Atomic generation — 4-6 scripts with screenshots between
+- DS component reuse — NEVER recreate existing components as raw frames
+- Registry loading — must load and cross-reference before generating
+- Canvas positioning — 80px+ gaps, no stacking at (0,0)
+- Script structure — follow figma-api-rules.md (Rule 17 / Rule 23)

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

@@ -128,6 +128,18 @@
 
 ---
 
+## Known Preferences
+
+> Learnings from previous designs that apply to this screen.
+> Populated automatically from `knowledge-base/learnings.json` during spec writing.
+> If none apply, write "None — no applicable learnings."
+
+| Rule | Scope | Signals |
+|------|-------|---------|
+| `{rule}` | {global / contextual} | {n} |
+
+---
+
 ## Responsive Rules
 
 | Breakpoint | Layout change |

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

@@ -124,6 +124,18 @@ interface {Composed}Props {
 
 ---
 
+## Known Preferences
+
+> Learnings from previous designs that apply to this component.
+> Populated automatically from `knowledge-base/learnings.json` during spec writing.
+> If none apply, write "None — no applicable learnings."
+
+| Rule | Scope | Signals |
+|------|-------|---------|
+| `{rule}` | {global / contextual} | {n} |
+
+---
+
 ## Component Properties (Figma)
 
 > Define ALL configurable properties for the Figma component.