@noemuch/bridge-ds 2.2.0 → 2.5.0

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

@@ -19,10 +19,10 @@
 - Load knowledge base registries for validation:
   - `references/knowledge-base/registries/components.json` → verify component instances match registry
   - `references/knowledge-base/registries/variables.json` → verify variable bindings use correct names
-- Inspect Figma design via MCP:
+- Inspect Figma design via MCP (tool names depend on transport — see `references/transport-adapter.md`):
   ```
-  figma_take_screenshot({ node_id: "{nodeId}", file_key: "{fileKey}" })
-  figma_get_variables({ file_key: "{fileKey}" })
+  Screenshot: console → figma_take_screenshot({ node_id, file_key }) / official → get_screenshot({ nodeId, fileKey })
+  Variables:  console → figma_get_variables({ file_key }) / official → get_variable_defs({ fileKey })
   ```
 
 ### 2. Review checklist
@@ -106,6 +106,17 @@ Cross-reference every visual element in the design against `registries/component
 - [ ] Could the props surface be smaller?
 - [ ] Is the component reusable beyond its primary use case?
 
+#### G. Learning Opportunity
+
+If the review identifies issues that the user may want to correct manually in Figma (spacing adjustments, token swaps, component replacements):
+
+```
+💡 After making corrections in Figma, run: `learn`
+   Bridge will detect your changes and remember them for future designs.
+```
+
+This hint is informational only — it does not block the review.
+
 ### 3. Report
 
 ```markdown

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):
@@ -35,6 +46,30 @@ Ask or infer from context:
 - 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`.
@@ -95,6 +130,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/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

@@ -446,6 +446,75 @@ 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 ✓
+```
+
+---
+
+## 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
@@ -497,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.