@noemuch/bridge-ds 2.3.0 → 2.5.1

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

@@ -0,0 +1,80 @@
+# Quick Mode — Express Design Generation
+
+## Purpose
+Generate a Figma design directly from a brief description, skipping the formal spec phase. Uses existing knowledge base, registries, and learnings. For when you need speed over ceremony.
+
+## Prerequisites
+- Knowledge base exists (registries populated) — if not, suggest: "Run `/design-workflow setup` first"
+- MCP transport available (see transport-adapter.md)
+
+## Procedure
+
+### Step 1 — Load context
+1. Load all registries (components.json, variables.json, text-styles.json)
+2. Load all guides (token usage, component overview, design patterns)
+3. Load learnings.json (apply all with scope=global + contextual matching description)
+4. Load ui-references guide if available
+
+### Step 2 — Gather intent (2 questions max)
+Ask the user exactly two things:
+1. **What to design**: brief description (e.g., "a settings page with profile section and notification preferences")
+2. **Where**: Figma file URL or file key + page name
+
+Do NOT ask for detailed content, states, responsive rules, or acceptance criteria. Infer reasonable defaults from the knowledge base and design patterns.
+
+### Step 3 — Pattern matching (best-effort)
+- Identify the screen type from the description
+- Load matching design patterns from guides/design-patterns.md
+- If ui-references/screenshots exist, identify the closest reference
+- This step is NON-BLOCKING — if no pattern matches, proceed with reasonable layout defaults
+- Note: in full mode, pattern matching is a blocking gate. In quick mode, it is best-effort.
+
+### Step 4 — Generate mini-spec (inline, not persisted)
+Write a condensed spec covering only:
+- **Layout**: zones, grid, overall structure (1-2 sentences)
+- **Sections**: list of sections with DS components to use (table format)
+- **Tokens**: key tokens for the layout (background, spacing rhythm)
+- **Known Preferences**: applicable learnings from learnings.json
+
+Format as a concise markdown block. Do NOT write to specs/active/. This lives only in the conversation.
+
+Show the mini-spec to the user and ask: "Generate this design?" (single yes/no confirmation)
+
+### Step 5 — Generate design
+Follow the same generation procedure as design.md steps 3-6:
+1. Read figma-api-rules.md (MANDATORY — same rules apply in quick mode)
+2. Determine canvas dimensions based on screen type
+3. **Pre-script audit** (MANDATORY — list every element, cross-reference against registries. Validate all keys per Rule 26.)
+4. Generate atomically in 4-6 scripts, ~30-80 lines each
+5. Take screenshot after each atomic step for verification — **but NOT before Script 1** (Rule 24: empty pages/frames cannot be screenshotted)
+6. For form inputs with values, use `state=filled` variant (Rule 25)
+7. Fix any issues before proceeding to next step
+
+IMPORTANT: These gates are NOT relaxed in quick mode:
+- Pre-script element audit (Rule 18) — BLOCKING
+- Registry key validation (Rule 26) — BLOCKING
+- Zero hardcoded hex colors — BLOCKING
+- Atomic generation with screenshots — MANDATORY
+- DS component reuse (never recreate) — BLOCKING
+
+### Step 6 — Present result
+Take a final screenshot of the complete design. Present to the user with:
+- Link to the Figma node
+- Summary of what was created (sections, components used, tokens applied)
+- Any learnings that were applied
+- Suggestion: "Run `/design-workflow review` for a formal quality check, or `/design-workflow learn` if you make corrections"
+
+## What is NOT done in quick mode
+- No formal spec file written to specs/active/
+- No formal review phase (but user can run review separately)
+- No automatic snapshot for learn (but user can run learn separately)
+- No pattern matching gate (best-effort only)
+- No acceptance criteria validation
+
+## Quality guarantee
+Even in quick mode, every design:
+- Uses 100% DS components (never raw recreations)
+- Uses 100% bound tokens (never hardcoded hex)
+- Is generated atomically with visual verification
+- Follows all 22+ figma-api-rules
+- Applies relevant learnings from previous corrections

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

@@ -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,71 @@ 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.**
+
+---
+
+## Rule 24: Never screenshot a page or empty node
+
+`figma_take_screenshot` / `get_screenshot` will fail on:
+- Page nodes (type PAGE) — they are not renderable
+- Empty frames (0 children) — nothing to render
+
+**Always create at least one visible frame before taking the first screenshot.** In quick mode and design mode, skip the initial screenshot attempt and wait until after Script 1 has created the root frame.
+
+---
+
+## Rule 25: Input/Select components — swap to `filled` state for values
+
+When placing TextInput, SelectInput, or similar form components with actual values (not empty placeholders), **always swap to the `state=filled` variant** before setting text properties. The default variant is often `state=placeholder`, which hides the value text layer.
+
+Pattern:
+```js
+// 1. Import the component set
+var inputSet = await figma.importComponentSetByKeyAsync(TEXTINPUT_KEY);
+
+// 2. Find the filled variant (not placeholder)
+var filled = inputSet.findChild(function(n) {
+  return n.name.includes("state=filled") || n.name.includes("state=filling");
+});
+
+// 3. Create instance from the filled variant
+var instance = filled.createInstance();
+
+// 4. Now set text properties — they will be visible
+instance.setProperties({ "label#HASH": "First Name", "placeholder#HASH": "John" });
+```
+
+If the DS has no `filled` variant, check for `default` or `rest` — but never leave `state=placeholder` when displaying real values.
+
+---
+
+## Rule 26: Validate registry keys before writing scripts
+
+Variable and component keys are 40-char hex strings — typos crash scripts at runtime with unhelpful errors like `could not find variable with key "..."`.
+
+**Before writing any figma_execute / use_figma script:**
+1. List every key you plan to use in the script
+2. Cross-reference each key against the exact values in `registries/variables.json`, `registries/components.json`, or `registries/text-styles.json`
+3. Copy-paste keys directly from the registry — never type them manually
+4. If a key is not found in registries, search with `Grep` before assuming the name
+
+This is part of the pre-script audit (Rule 18). Every key in the script must have a verified source in the registries.
+
+---
+
 ## Standard Script Boilerplate
 
 ```js
@@ -550,3 +615,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.