@noemuch/bridge-ds 2.5.0 → 2.5.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "bridge-ds",
   "displayName": "Bridge Design System",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "AI-powered design generation in Figma — spec-first, DS-native, with a learning loop that improves over time. Extracts your real design system, writes validated specs, and generates production-ready Figma designs using actual DS components and tokens.",
   "author": {
     "name": "noemuch",

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "bridge-ds",
   "displayName": "Bridge Design System",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "AI-powered design generation in Figma — spec-first, DS-native, with a learning loop.",
   "author": "noemuch",
   "homepage": "https://github.com/noemuch/bridge",

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to Bridge DS are documented here.
 
+## [2.5.1] — 2026-03-25
+
+### Added
+- **Rule 24**: Never screenshot a page or empty node — create a frame first
+- **Rule 25**: Input/Select components — swap to `state=filled` for real values
+- **Rule 26**: Validate registry keys before writing scripts — copy-paste from registries, never type manually
+- `quick.md`: References Rules 24-26 in generation steps
+
+## [2.5.0] — 2026-03-25
+
+### Added
+- **Dual MCP transport**: Support for both figma-console-mcp (preferred) and official Figma MCP server (fallback). Auto-detection picks the best available transport.
+- **Express mode**: `/design-workflow quick` skips formal spec, generates from brief description with 2 questions max. Same DS quality guarantees.
+- **Plugin packaging**: `.claude-plugin/plugin.json` and `.cursor-plugin/plugin.json` for marketplace distribution.
+- **Transport adapter**: `transport-adapter.md` — central reference for tool mapping, script adaptation, and composite DS extraction.
+- **Rule 23**: Transport-aware scripting in `figma-api-rules.md` (IIFE vs top-level await, official transport constraints).
+- **KB path resolution**: `./bridge-ds/` (plugin mode) or `.claude/skills/` (npm scaffold mode).
+- **`.mcp.json`**: MCP server dependency declaration for plugin installs.
+
+### Changed
+- `mcp-setup.js`: Returns `{ console, official }` instead of boolean.
+- `cli.js`: Reports both transports during init, offers dual setup instructions.
+- `onboarding.md`: Dual transport detection + composite DS extraction for official transport.
+- `quality-gates.md`: Quick mode section with relaxed gates (pattern matching best-effort, no formal spec/review).
+- 6 schema files updated with transport notes.
+- `package.json`: Bumped to v2.5.0, added plugin manifests to `files`.
+
 ## [2.4.1] — 2026-03-20
 
 ### Fixed

package/README.md

@@ -8,8 +8,9 @@ Bridge turns [Claude Code](https://claude.ai/download) into a designer that know
 You describe what you want
   → Claude consults the knowledge base (your DS, documented)
   → Claude writes the spec (exact components, tokens, layout)
-  → Claude generates in Figma via figma_execute (real DS components, bound variables)
+  → Claude generates in Figma (real DS components, bound variables)
   → You review in Figma
+  → Claude learns from your corrections (and improves next time)
 ```
 
 ## How it works
@@ -19,21 +20,23 @@ Bridge is two things:
 1. **A CLI** (`bridge-ds init`) that scaffolds your project with the design workflow skill
 2. **A Claude Code skill** (`/design-workflow`) that handles the intelligence — spec writing, DS knowledge, Figma generation
 
-The transport layer is [figma-console-mcp](https://github.com/southleft/figma-console-mcp), an MCP server that gives Claude native access to Figma (57+ tools).
+Bridge supports two MCP transports:
 
 ```
-Claude Code  ──MCP──>  figma-console-mcp  ──WebSocket──>  Figma Desktop
-                                                            (your DS library,
-                                                             real components,
-                                                             bound variables)
+Claude Code  ──MCP──>  figma-console-mcp  ──WebSocket──>  Figma Desktop  (preferred)
+Claude Code  ──MCP──>  Figma MCP Server   ──Cloud──>      Figma Cloud    (official, fallback)
 ```
 
+Auto-detection picks the best available transport. See [transport-adapter.md](skills/design-workflow/references/transport-adapter.md) for details.
+
 ## Prerequisites
 
 - [Claude Code](https://claude.ai/download) installed
 - [Node.js 18+](https://nodejs.org)
-- [Figma Desktop](https://www.figma.com/downloads/) (not the web app)
 - A Figma file with a published design system library
+- One of:
+  - [figma-console-mcp](https://github.com/southleft/figma-console-mcp) + [Figma Desktop](https://www.figma.com/downloads/) (recommended, full capabilities)
+  - Official Figma MCP server (simpler setup, cloud-based)
 
 ## Quick Start
 
@@ -104,6 +107,9 @@ setup (once)  →  spec  →  design  →  review  ──→  done
                                             extract preferences)
 ```
 
+### Express mode
+For quick iterations, skip the formal spec: `/design-workflow quick "a settings page"`. 2 questions max, inline mini-spec, same DS quality guarantees.
+
 ### Spec-first
 No design without a validated specification. Claude knows exactly which components, tokens, and layout patterns to use because it has your DS documented.
 
@@ -139,6 +145,7 @@ knowledge-base/
 | `/design-workflow setup` | Extract DS + build knowledge base |
 | `/design-workflow spec {name}` | Write a component or screen spec |
 | `/design-workflow design` | Generate in Figma from active spec |
+| `/design-workflow quick {description}` | Express generation — skip spec, generate directly |
 | `/design-workflow review` | Validate design against spec + tokens |
 | `/design-workflow done` | Archive spec and ship |
 | `/design-workflow drop` | Abandon with preserved learnings |
@@ -146,6 +153,10 @@ knowledge-base/
 | `/design-workflow sync` | Incremental DS sync (no full re-setup) |
 | `/design-workflow status` | Show current state, suggest next action |
 
+## Author
+
+Built by [Noé Chagué](https://www.linkedin.com/in/noechague/) — Design System @ [Finary](https://finary.com)
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noemuch/bridge-ds",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "AI-powered design generation in Figma — 100% design system compliant. Connects Claude Code to Figma via MCP for spec-first, token-bound, component-native design.",
   "main": "lib/cli.js",
   "bin": {

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

@@ -44,13 +44,15 @@ Show the mini-spec to the user and ask: "Generate this design?" (single yes/no c
 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)
+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
-6. Fix any issues before proceeding to next step
+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

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

@@ -515,6 +515,55 @@ Script format depends on the active MCP transport. See `references/transport-ada
 
 ---
 
+## 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