@noemuch/bridge-ds 2.3.0 → 2.5.0

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.

package/skills/design-workflow/references/transport-adapter.md

@@ -0,0 +1,210 @@
+# Transport Adapter — Dual MCP Transport Support
+
+> **Single source of truth for transport detection, tool mapping, and script adaptation.**
+> All other reference files point here instead of duplicating transport logic.
+
+---
+
+## A. Transport Detection
+
+Before any Figma operation, determine which transport is active:
+
+1. **Check for console transport:** Is `figma_execute` available?
+2. **Check for official transport:** Is `use_figma` available?
+
+| Result | Transport | Action |
+|--------|-----------|--------|
+| `figma_execute` available | **Console** (preferred) | Use console tool names throughout |
+| `use_figma` available (no console) | **Official** | Use official tool names, apply adaptation rules below |
+| Both available | **Console** (preferred) | Console is more capable, no response limits |
+| Neither available | **Blocked** | Show setup instructions for both options (see below) |
+
+**Block message when neither is available:**
+```
+No Figma MCP transport detected. Configure one of these:
+
+Option A — figma-console-mcp (recommended, full Plugin API access):
+  claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN -- npx -y figma-console-mcp@latest
+
+Option B — Official Figma MCP (cloud-based, cross-library search):
+  Configure via Claude settings or Figma's MCP integration.
+```
+
+---
+
+## B. Tool Mapping Table
+
+| Bridge Operation | Console (preferred) | Official Figma MCP | Notes |
+|---|---|---|---|
+| Execute Plugin API code | `figma_execute` | `use_figma` | Different wrapper format (see Section C) |
+| Take screenshot | `figma_take_screenshot` | `get_screenshot` | Official requires `nodeId` + `fileKey` |
+| Full DS extraction | `figma_get_design_system_kit` | Composite strategy (see Section D) | |
+| Get variables | `figma_get_variables` | `get_variable_defs` | |
+| Get styles | `figma_get_styles` | `search_design_system` (includeStyles) | |
+| Connection check | `figma_get_status` | `whoami` + test `use_figma` call | See Section F |
+| Search components | `figma_search_components` | `search_design_system` (includeComponents) | Official searches cross-library |
+| Get component | `figma_get_component` | `get_design_context` or `get_metadata` | |
+
+---
+
+## C. Script Adaptation Rules
+
+### Console transport (figma_execute)
+
+IIFE wrapper is **mandatory**. The `return` before the IIFE is required.
+
+```javascript
+// Console: figma_execute({ code: "..." })
+return (async function() {
+  await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+  // ... Plugin API code ...
+  return { success: true };
+})();
+```
+
+### Official transport (use_figma)
+
+Top-level `await` — **no IIFE wrapper**. Requires `fileKey` and `description` parameters.
+
+```javascript
+// Official: use_figma({ fileKey: "...", description: "...", code: "..." })
+await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+// ... Plugin API code ...
+return { success: true };
+```
+
+### Key differences
+
+| Aspect | Console | Official |
+|--------|---------|----------|
+| Wrapper | `return (async function() { ... })();` | Top-level `await`, no IIFE |
+| Parameters | `{ code }` | `{ fileKey, description, code }` |
+| `figma.notify()` | Allowed | **Forbidden** (no UI access) |
+| `getPluginData()` | Allowed | **Forbidden** (use `getSharedPluginData()`) |
+| Response size | Unlimited | **20KB limit** — chunk large extractions |
+| Document access | Current file via plugin | Specified file via `fileKey` |
+
+### Transformation example
+
+**Same script in both formats:**
+
+Console:
+```javascript
+return (async function() {
+  await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+  var frame = figma.createFrame();
+  frame.name = "Test";
+  frame.resize(400, 300);
+  figma.currentPage.appendChild(frame);
+  return { id: frame.id, name: frame.name };
+})();
+```
+
+Official:
+```javascript
+await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+var frame = figma.createFrame();
+frame.name = "Test";
+frame.resize(400, 300);
+figma.currentPage.appendChild(frame);
+return { id: frame.id, name: frame.name };
+```
+
+Called as: `use_figma({ fileKey: "YOUR_FILE_KEY", description: "Create a test frame", code: "..." })`
+
+---
+
+## D. DS Extraction Composite Strategy
+
+When `figma_get_design_system_kit` is unavailable (official transport), extract DS data using multiple tools:
+
+### 1. Variables
+
+```
+get_variable_defs({ fileKey }) → collection/variable structure
+```
+
+If `get_variable_defs` does not return keys suitable for `importVariableByKeyAsync`, supplement with a `use_figma` extraction script (same script as in `schemas/variables.md`, without the IIFE wrapper).
+
+### 2. Components
+
+```
+search_design_system({ query: "*", includeComponents: true }) → component list
+```
+
+Run broad queries per category (e.g., "Button", "Input", "Card") to cover the DS. For detailed component properties, use `use_figma` with the extraction script from `schemas/components.md` (without IIFE wrapper).
+
+### 3. Styles
+
+```
+search_design_system({ query: "*", includeStyles: true }) → text/color/effect styles
+```
+
+If keys are not returned, supplement with a `use_figma` extraction script (from `schemas/text-styles.md`, without IIFE wrapper).
+
+### 4. Assembly
+
+Assemble extracted data into the same registry JSON format defined in the schemas. The output registries must be identical regardless of which transport was used for extraction.
+
+---
+
+## E. Screenshot Adaptation
+
+### Console
+
+```
+figma_take_screenshot({ node_id: "123:456" })
+```
+
+`node_id` is optional — omitting it captures the current viewport.
+
+### Official
+
+```
+get_screenshot({ nodeId: "123:456", fileKey: "abc123" })
+```
+
+Both `nodeId` and `fileKey` are **required**. Track these values throughout the workflow:
+- `fileKey`: obtained when the user provides the Figma file URL
+- `nodeId`: returned by script execution (root frame ID from generation steps)
+
+---
+
+## F. Connection Check Adaptation
+
+### Console
+
+```
+figma_get_status() → { setup: { valid: true }, ... }
+```
+
+Success: `setup.valid === true` means Figma Desktop is connected.
+
+### Official
+
+```
+whoami() → { name: "...", email: "..." }
+```
+
+Success means the user is authenticated. Then test actual file access:
+```
+use_figma({ fileKey: "...", description: "Connection test", code: "return { page: figma.currentPage.name };" })
+```
+
+If both succeed, the official transport is operational.
+
+---
+
+## G. Official Transport Bonus Capabilities
+
+These tools are only available on the official transport and provide additional functionality:
+
+| Tool | Capability |
+|------|------------|
+| `search_design_system` | **Cross-library search** — finds components/styles across all team libraries, not just the current file |
+| `get_code_connect_map` | Retrieve Code Connect mappings between Figma components and code |
+| `add_code_connect_map` | Create Code Connect mappings |
+| `create_design_system_rules` | Export design system rules |
+| `generate_figma_design` | Capture a web page into Figma (web-to-Figma) |
+| `get_design_context` | Rich component context with code hints |
+| `get_metadata` | File-level metadata and structure |