@mp3wizard/figma-console-mcp 1.32.2 → 1.34.1

package/README.md

@@ -8,16 +8,16 @@
 
 > **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, **debugging**, and **bidirectional token sync**.
 
-> **🆕 Accessibility auditing now matches WCAG, not folklore (v1.32.0):** `figma_lint_design` no longer red-flags line height below 1.5× as an accessibility failure. **WCAG 1.4.12 Text Spacing** only requires that content *support* a user overriding text spacing without loss — not that designs *ship* at 1.5× — so a sub-1.5 line height is not a conformance failure. Line and paragraph spacing checks are now scoped to multi-line text (single-line labels, buttons, and headings are exempt), the readability hints are split into an opt-in `best-practice` group so `rules: ['wcag']` stays pure conformance, and the real 1.4.12 check now lives on the code side in `figma_scan_code_accessibility`. **Re-import the plugin once** to pick up the new audit behavior. [See what's new →](CHANGELOG.md#1320---2026-06-20)
+> **🆕 Bidirectional Token Sync v2 + DTCG 2025.10 (v1.34.0):** `figma_import_tokens` now applies the *whole* diff plan — creates, renames, alias re-targeting, and replace-gated deletes — for a true code→Figma round-trip; exports speak DTCG 2025.10 on request (opt-in, legacy default byte-identical); scopes/codeSyntax round-trip; `figma_setup_design_tokens` accepts alias values; and the new `figma_create_component_set` builds a full variant set from an axes matrix in one call. **Plugin re-import required** (`code.js` + `ui.html` changed). [See what's new →](CHANGELOG.md#1340---2026-07-03)
 
 ## What is this?
 
 Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 - **🎨 Design system extraction** - Pull variables, components, and styles
-- **🔁 Bidirectional token sync** - Export Figma variables to DTCG JSON + CSS custom properties; push code-side edits back to Figma. Replaces Style Dictionary and Tokens Studio's export pipeline.
+- **🔁 Bidirectional token sync** - Export Figma variables to DTCG JSON (legacy or 2025.10 dialect) + 9 more formats; push code-side edits back to Figma with full apply — creates, renames, alias re-targeting, and replace-gated deletes. Replaces Style Dictionary and Tokens Studio's export pipeline.
 - **📸 Visual debugging** - Take screenshots for context
-- **✏️ Design creation** - Create UI components, frames, and layouts directly in Figma
+- **✏️ Design creation** - Create UI components, frames, and layouts directly in Figma — including one-call component-set creation from a variant axes matrix
 - **🔧 Variable management** - Create, update, rename, and delete design tokens
 - **🕰 Version history & time-series awareness** - List versions, diff snapshots, generate markdown changelogs, trace property/variant introduction via binary-search blame
 - **⚡ Real-time monitoring** - Watch console logs from the Desktop Bridge plugin
@@ -55,9 +55,9 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 | Real-time monitoring (console, selection) | ✅ | ❌ | ❌ |
 | Desktop Bridge plugin | ✅ | ✅ | ❌ |
 | Requires Node.js | Yes | **No** | No |
-| **Total tools available** | **106** | **95** | **9** |
+| **Total tools available** | **107** | **96** | **9** |
 
-> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 106 tools with real-time monitoring.
+> **Bottom line:** Remote SSE is **read-only** with 9 tools. **Cloud Mode** unlocks write access (96 tools) from web AI clients without Node.js. NPX/Local Git gives the full 107 tools with real-time monitoring.
 
 ---
 
@@ -65,7 +65,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 **Best for:** Designers who want full AI-assisted design capabilities.
 
-**What you get:** All 106 tools including design creation, variable management, and component instantiation.
+**What you get:** All 107 tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -162,7 +162,7 @@ Create a simple frame with a blue background
 
 **Best for:** Developers who want to modify source code or contribute to the project.
 
-**What you get:** Same 106 tools as NPX, plus full source code access.
+**What you get:** Same 107 tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -251,7 +251,7 @@ Ready for design creation? Follow the [NPX Setup](#-npx-setup-recommended) guide
 
 **Best for:** Using Claude.ai, v0, Replit, or Lovable to create and modify Figma designs — no Node.js required.
 
-**What you get:** 95 tools including full write access — design creation, variable management, component instantiation, and all REST API tools. Only real-time monitoring (console logs, selection tracking, document changes) requires Local Mode.
+**What you get:** 96 tools including full write access — design creation, variable management, component instantiation, and all REST API tools. Only real-time monitoring (console logs, selection tracking, document changes) requires Local Mode.
 
 #### Prerequisites
 
@@ -308,7 +308,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | Feature | NPX (Recommended) | Cloud Mode | Local Git | Remote SSE |
 |---------|-------------------|------------|-----------|------------|
 | **Setup time** | ~10 minutes | ~5 minutes | ~15 minutes | ~2 minutes |
-| **Total tools** | **106** | **95** | **106** | **9** (read-only) |
+| **Total tools** | **107** | **96** | **107** | **9** (read-only) |
 | **Design creation** | ✅ | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
@@ -323,7 +323,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | **Automatic updates** | ✅ (`@latest`) | ✅ | Manual (`git pull`) | ✅ |
 | **Source code access** | ❌ | ❌ | ✅ | ❌ |
 
-> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 106 tools.
+> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 107 tools.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -415,6 +415,10 @@ When you first use design system tools:
   - Create frames, shapes, text, components
   - Apply auto-layout, styles, effects
   - Build complete UI mockups programmatically
+- `figma_create_component_set` - **Create a component set with variants in one declarative call**
+  - Generate every variant combination from an axes matrix (e.g. `{ State: ["default", "hover", "disabled"], Size: ["sm", "lg"] }` → 6 variants) off a base component, or combine existing components
+  - `Prop=Value` variant naming, `combineAsVariants` under the hood, optional auto-arranged labeled grid
+  - Returns each variant's key, ready for `figma_instantiate_component`
 - `figma_arrange_component_set` - **Organize variants into professional component sets**
   - Convert multiple component variants into a proper Figma component set
   - Applies native purple dashed border visualization automatically
@@ -432,8 +436,8 @@ When you first use design system tools:
 - `figma_generate_component_doc` - Generate platform-agnostic markdown documentation by merging Figma design data with code-side info
 
 ### 🔁 Token Sync (Local Mode + Cloud Mode)
-- `figma_export_tokens` - **Export Figma variables to design token files in your codebase.** Canonical DTCG JSON + CSS custom properties out of the box. Diff-aware merge against existing source files (only writes what changed). `tokens.config.json` autodiscovery means zero-arg calls after first setup. Replaces Style Dictionary and Tokens Studio's export pipeline for popular styling methods.
-- `figma_import_tokens` - **Push code-side token edits back to Figma.** Diff against current Figma state, apply only the deltas. Round-trip safe — Figma variable IDs preserved in DTCG `$extensions["figma-console-mcp"]` so renames on either side don't create duplicates. Dry-run default for safety. In Cloud Mode, pass tokens inline via `payload` or `files` (no local filesystem access).
+- `figma_export_tokens` - **Export Figma variables to design token files in your codebase.** Canonical DTCG JSON (legacy hex dialect by default, or DTCG 2025.10 object colors/dimensions via `dtcgDialect: "2025"`) plus CSS, Tailwind v4/v3, SCSS, TS, JSON, Style Dictionary, and Tokens Studio formats. Diff-aware merge against existing source files (only writes what changed). `tokens.config.json` autodiscovery means zero-arg calls after first setup. Scopes and codeSyntax metadata round-trip via `$extensions`. Replaces Style Dictionary and Tokens Studio's export pipeline for popular styling methods.
+- `figma_import_tokens` - **Push code-side token edits back to Figma with a full apply phase.** Diffs against current Figma state, then applies value updates, **creates** missing collections/variables, applies **renames**, writes real **alias** (`VARIABLE_ALIAS`) references, and — only under `strategy: "replace"` — deletes Figma-only variables. Round-trip safe — Figma variable IDs preserved in DTCG `$extensions["figma-console-mcp"]` so renames on either side don't create duplicates. Accepts both DTCG dialects. Dry-run strategy for safe previews. In Cloud Mode, pass tokens inline via `payload` or `files` (no local filesystem access).
 
 ### 🔧 Variable Management (Local Mode + Cloud Mode)
 - `figma_create_variable_collection` - Create new variable collections with modes
@@ -446,7 +450,7 @@ When you first use design system tools:
 - `figma_rename_mode` - Rename existing modes
 - `figma_batch_create_variables` - Create up to 100 variables in one call (10-50x faster)
 - `figma_batch_update_variables` - Update up to 100 variable values in one call
-- `figma_setup_design_tokens` - Create complete token system (collection + modes + variables) atomically
+- `figma_setup_design_tokens` - Create complete token system (collection + modes + variables) atomically — values accept DTCG brace references (`"{color.blue.600}"`) that resolve to real variable aliases
 
 ### 📌 FigJam Board Tools (Local Mode + Cloud Mode)
 - `figjam_create_sticky` - Create a sticky note with color options
@@ -669,7 +673,7 @@ The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to t
 - The MCP server communicates via **WebSocket** through the Desktop Bridge plugin
 - The server tries port 9223 first, then automatically falls back through ports 9224–9232 if needed
 - The plugin scans all ports in the range and connects to every active server it finds
-- All 106 tools work through the WebSocket transport
+- All 107 tools work through the WebSocket transport
 
 **Multiple files:** The WebSocket server supports multiple simultaneous plugin connections — one per open Figma file. Each connection is tracked by file key with independent state (selection, document changes, console logs).
 
@@ -808,9 +812,14 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.32.0 (Stable) - Production-ready with WCAG-accurate accessibility auditing (line height below 1.5× is no longer mis-flagged as a failure; readability hints decoupled from conformance checks and scoped to multi-line text; code-side WCAG 1.4.12 check), a self-healing Desktop Bridge connection (zombie-process reaper + auto-reconnect watchdog — fixes the recurring "not connected until restart" bug), native variable binding on fills/strokes + typography control in the write tools, shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **106 tools** (Local) / **95 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
+**Current Status:** v1.34.0 (Stable) - Production-ready. Latest: Bidirectional Token Sync v2 + DTCG 2025.10 — `figma_import_tokens` now applies the complete diff plan (creates missing collections/variables, applies renames, writes real `VARIABLE_ALIAS` references, and deletes only under explicit `replace`), `figma_export_tokens` speaks the DTCG 2025.10 dialect on request (legacy default byte-identical), variable scopes/codeSyntax round-trip via `$extensions`, `figma_setup_design_tokens` accepts alias values via DTCG brace references, and the new `figma_create_component_set` builds a full variant set from an axes matrix in one call. On top of the v1.33.x line: version-handshake fix (re-import banner only fires when plugin files actually changed), security dependency sweep, and the v1.33.0 connection UX overhaul (honest status pill derived from live connection state, `/health` auto-discovery with self-healing reconnect) + a 33-fix full-codebase audit (lossless DTCG multi-mode round-trips, cross-collection alias resolution, branch-URL correctness across REST tools, cache-poisoning and CSWSH fixes, bridge-first screenshots). Built on WCAG-accurate accessibility auditing (line height below 1.5× is no longer mis-flagged as a failure; readability hints decoupled from conformance checks and scoped to multi-line text; code-side WCAG 1.4.12 check), a self-healing Desktop Bridge connection (zombie-process reaper + auto-reconnect watchdog — fixes the recurring "not connected until restart" bug), native variable binding on fills/strokes + typography control in the write tools, shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **107 tools** (Local) / **96 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [x] **v1.34.0** - Bidirectional Token Sync v2 + DTCG 2025.10. `figma_import_tokens` now applies the *complete* diff plan: missing collections and variables are created (with modes, inferred/recorded types, and values set in dependency order — aliases in a second pass), token-path renames route to the update phase by round-trip variable ID (no more create+delete pairs that would permanently destroy the original under `replace`), reference values write real `{ type: "VARIABLE_ALIAS", id }` payloads via a four-tier resolver, and deletes are strictly gated behind `strategy: "replace"`. `figma_export_tokens` gains `dtcgDialect: "2025"` (object-form colors from full-precision floats, object dimensions) while the legacy default stays byte-identical; import accepts both dialects unconditionally with dialect-insensitive diff normalization. Variable `scopes` + `codeSyntax` round-trip through `$extensions["figma-console-mcp"]`. `figma_setup_design_tokens` accepts DTCG brace references (`"{color.blue.600}"`) that resolve to real aliases, including forward references. New tool `figma_create_component_set` builds a variant set from an axes matrix (or combines existing components) with `Prop=Value` naming, optional auto-arranged grid, and variant keys in the response — with count-scaled timeouts and rollback on failure. **Plugin re-import required** (`code.js` + `ui.html` changed — the component-set handler and relay). 183 tests across the token/write-tools suites.
+- [x] **v1.33.2** - Version-handshake false-positive fix. The v1.33.0 handshake compared the plugin's reported version against the server's *package* version, so server-only releases (like the v1.33.1 dependency sweep) flagged every up-to-date plugin as stale and pushed the re-import banner for files that hadn't changed. The server now compares against the `PLUGIN_VERSION` embedded in the `figma-desktop-bridge/code.js` it ships — exactly what a re-import would install — and `PLUGIN_VERSION` itself now means "last release in which plugin files changed" (release tooling bumps it only when `figma-desktop-bridge/` actually changed since the last tag). `figma_get_status` gains `transport.websocket.bundledPluginVersion`; `figma_diagnose` blames the right version. No new tools, **no plugin re-import required** (one-time exception: if you re-imported at v1.33.1, the banner appears once more — clear it with one final re-import). 1245 tests passing (9 new).
+- [x] **v1.33.1** - Security dependency sweep. All runtime and critical npm audit alerts resolved via in-range bumps (`ws` 8.21.0, `hono` 4.12.27, `undici` 7.28.0, `handlebars` 4.7.9 — the lone critical, dev-only — plus `lodash`, `path-to-regexp`, `basic-ftp`, `fast-uri`, `vite`). `wrangler` deliberately held at 4.72.0 because newer versions require Node ≥22; the only residual audit findings are inside wrangler/miniflare's dev-time toolchain, which never ships in the npm package or Worker bundle. Supersedes dependabot PRs #81/#82/#84. No code changes, no API changes, no plugin re-import. 1236 tests passing unchanged.
+- [x] **v1.33.0** - Connection UX overhaul + full-codebase audit. The plugin's status pill now derives from live connection state instead of Figma's variables loading (it used to glow green with zero MCP servers connected); HTTP `/health` auto-discovery reconnects restarted servers automatically (including one-dead-among-live, previously a permanent dead end); a version handshake banners the plugin UI when a re-import is needed and surfaces the mismatch in `figma_get_status`/`figma_diagnose`; cloud pairing config survives plugin reopen and its status line is derived + labeled (no more orphaned "Disconnected" under a green pill); all plugin copy is designer-language. The audit fixed 33 verified issues: lossless DTCG multi-mode round-trips, set-qualified cross-collection aliases, TIMING/EASING mapped to DTCG `duration`/`cubicBezier`, two cache-poisoning bugs (the "search returns 0 components" reports), a CSWSH origin bypass (`startsWith` → exact match), post-sleep reaper kill-safety (plus a shell-free `/health` probe with `os.devNull` so Windows curl can't false-negative a healthy sibling), branch-URL correctness across REST tools, and bridge-first `figma_take_screenshot`. `figma_arrange_component_set` now rearranges variants in place so placed instances survive. No new tools; **plugin re-import required** (`code.js` + `ui.html` changed — and the new handshake makes this the last one you have to discover on your own). 1236 tests passing (33 new).
+- [x] **v1.32.1** - Documentation-generator fix reported by Robin Di Capua: `figma_generate_component_doc` documented **colors** as raw hex (with `—` in the Figma Variable column) even when fills/strokes were bound to variables, while spacing tokens documented correctly. Two root causes — an id→name lookup that read the wrong keys (`.id`/`.name` instead of `variableId`/`variableName`), and variable names only ever being sourced from the Enterprise-only REST `/variables/local` endpoint (403 elsewhere). The generator now resolves names via the Desktop Bridge Plugin API (works on every plan) and threads them through the States, Color Tokens, and Spacing tables, so real token names like `color/content/default` and `spacing/1` appear. No new tools, no arg-shape changes, no plugin re-import required. 1203 tests passing.
 - [x] **v1.32.0** - Accessibility-audit correctness fix reported by Isabella (a11y collaborator): `figma_lint_design` was flagging line height below 1.5× as an accessibility failure on hundreds of components. That misreads **WCAG 1.4.12 Text Spacing**, which requires content to *support* user spacing overrides without loss — not that designs *ship* at 1.5× — so a sub-1.5 line height is not a conformance failure. Line/paragraph-spacing checks are now scoped to multi-line text (single-line labels and buttons exempt); readability hints (`text-size`, `line-height`, `letter-spacing`, `paragraph-spacing`) are decoupled from the `wcag` group into an opt-in `best-practice` group, so the default audit (`['wcag','design-system','layout']`) and `rules: ['wcag']` return genuine conformance only; and a new code-side `text-spacing-support` advisory in `figma_scan_code_accessibility` flags fixed-px typography — where 1.4.12/1.4.4 are actually verifiable. No new tools, no arg-shape changes; **plugin re-import required** to pick up the new audit behavior (bridge protocol unchanged, so an un-updated plugin stays compatible). 1196 tests passing.
 - [x] **v1.31.0** - Fixes the most-reported reliability bug: the Desktop Bridge connection dropping and staying down until you closed the plugin, restarted your MCP client, or killed ports by hand. Root cause was **zombie MCP server processes** squatting the WebSocket port range (9223–9232) after a bad shutdown. The reaper now escalates `SIGTERM` → `SIGKILL` (a hung server that ignores graceful shutdown can no longer survive), sweeps the range every 5 minutes via an `unref`'d periodic reaper, and a shutdown backstop prevents a server from zombifying in the first place. The redesigned Desktop Bridge plugin adds an auto-reconnect watchdog (re-probes every ~12s while disconnected), a context-aware **Pause / Resume / Reconnect** button, and a live server-count badge. No new tools; **plugin re-import required** (bridge `ui.html` + `code.js` changed). 1190 tests passing, including an integration test that spawns a real `SIGTERM`-ignoring process and asserts the reaper kills it.
 - [x] **v1.30.0** - Native variable binding + typography in the structured write tools, closing the Plugin API gaps that used to force raw `figma_execute`. `figma_set_fills` / `figma_set_strokes` accept a `variableId` to bind a fill/stroke to a color variable via `setBoundVariableForPaint` (any plan, via the bridge). `figma_set_text` gains `fontFamily` / `fontStyle` with space-insensitive normalization (`SemiBold` → `Semi Bold`) and graceful `Regular` fallback. `figma_instantiate_component` pre-loads instance text fonts before applying overrides (fixes silently-skipped text overrides on non-Regular weights) and returns a `warnings` array for failed overrides. Also fixes a mixed-font crash in `figma_set_text` and a `ui.html` relay that was dropping new message fields. No new tools; **plugin re-import required** (bridge `ui.html` + `code.js` changed). Validated live; 1185 tests passing.
@@ -835,10 +844,10 @@ The architecture supports adding new apps with minimal boilerplate — each app
 - [x] **v1.7.0** - MCP Apps (Token Browser, Design System Dashboard), batch variable operations, design-code parity tools.
 
 **Coming Next:**
-- [ ] **Token sync — parsers + import-side apply expansion** - Parsers for non-DTCG input (Tokens Studio, CSS vars, Tailwind v4, Tailwind v3 config, SCSS, Style Dictionary v3, JSON flat/nested). Plus `toCreate` apply orchestration, `toDelete` for `replace` strategy, alias-target updates, and cross-library variable resolution via `getVariableByIdAsync` so cross-library aliases render as real `var(--target)` references instead of comments.
+- [ ] **Token sync — non-DTCG input parsers** - Parsers for non-DTCG input (Tokens Studio, CSS vars, Tailwind v4, Tailwind v3 config, SCSS, Style Dictionary v3, JSON flat/nested) so `figma_import_tokens` can ingest the same formats it exports. (The import-side apply expansion — creates, replace-gated deletes, alias-target updates — shipped in v1.34.0.)
+- [ ] **Cross-library variable resolution** - Resolve cross-library aliases via `getVariableByIdAsync` so they render as real `var(--target)` references in exports instead of comments.
 - [ ] **Component template library** - Common UI pattern generation
 - [ ] **Visual regression testing** - Screenshot diff capabilities
-- [ ] **Design linting** - Automated compliance and accessibility checks
 
 **📖 [Full Roadmap](docs/ROADMAP.md)**
 

package/dist/cloudflare/core/cloud-websocket-connector.js

@@ -180,6 +180,24 @@ export class CloudWebSocketConnector {
         }
         return this.sendCommand('INSTANTIATE_COMPONENT', params);
     }
+    async createComponentSet(params) {
+        // Timeout scales with variant count — the plugin builds all variants in
+        // one uncancellable pass, so a fixed 30s ceiling on big matrices reports
+        // failure while the set still gets created (retry → duplicates).
+        // Mirrors componentSetTimeoutMs in websocket-connector.ts (not imported:
+        // that module pulls the Node 'ws' stack into the Workers bundle).
+        let variantCount = 1;
+        if (params.componentIds?.length) {
+            variantCount = params.componentIds.length;
+        }
+        else if (params.properties) {
+            for (const values of Object.values(params.properties)) {
+                variantCount *= Math.max(1, values?.length ?? 1);
+            }
+        }
+        const timeout = Math.min(120000, Math.max(30000, variantCount * 1200)) + 5000;
+        return this.sendCommand('CREATE_COMPONENT_SET', params, timeout);
+    }
     // ============================================================================
     // Node manipulation
     // ============================================================================

package/dist/cloudflare/core/design-code-tools.js

@@ -477,7 +477,7 @@ function buildAnatomyLines(node, lines, prefix, isLast, depth, maxDepth) {
 /**
  * Collect spacing tokens with their bound variable names.
  */
-function collectSpacingTokens(node) {
+function collectSpacingTokens(node, varNameMap = new Map()) {
     const tokens = [];
     const boundVars = node.boundVariables || {};
     const spacingProps = [
@@ -493,7 +493,11 @@ function collectSpacingTokens(node) {
         const value = node[key];
         if (value !== undefined && value !== null) {
             const varBinding = boundVars[key];
-            const varName = varBinding?.id || varBinding?.name;
+            // Bound spacing variables expose their id as boundVariables[key].id.
+            // Resolve it to a friendly token name (e.g. `spacing/1`) when the caller
+            // supplied a name map; fall back to the raw id so the binding stays visible.
+            const varId = typeof varBinding?.id === "string" ? varBinding.id : undefined;
+            const varName = varId ? varNameMap.get(varId) || varId : undefined;
             tokens.push({
                 property: label,
                 value,
@@ -843,20 +847,26 @@ function compareTokens(enrichedData, codeSpec, discrepancies) {
             });
         }
     }
-    // Cross-reference design variables with code tokens
+    // Cross-reference design variables with code tokens.
+    // enrichment entries key off variableName (NOT name); reading `.name` here left
+    // every comparison undefined (and would throw on .toLowerCase()). Use variableName
+    // and skip any entries that never resolved to a real token name.
     if (enrichedData.variables_used && ct.usedTokens) {
-        const designTokenNames = enrichedData.variables_used.map((v) => v.name.toLowerCase());
+        const designTokens = enrichedData.variables_used
+            .map((v) => v.variableName)
+            .filter((n) => typeof n === "string" && n.length > 0);
+        const designTokenNames = designTokens.map((n) => n.toLowerCase());
         const codeTokenNames = ct.usedTokens.map((t) => t.toLowerCase());
-        for (const designToken of enrichedData.variables_used) {
-            const normalizedName = designToken.name.toLowerCase();
+        for (const tokenName of designTokens) {
+            const normalizedName = tokenName.toLowerCase();
             if (!codeTokenNames.some((ct) => ct.includes(normalizedName) || normalizedName.includes(ct))) {
                 discrepancies.push({
                     category: "tokens",
-                    property: `token:${designToken.name}`,
+                    property: `token:${tokenName}`,
                     severity: "minor",
-                    designValue: designToken.name,
+                    designValue: tokenName,
                     codeValue: null,
-                    message: `Design uses token "${designToken.name}" but code doesn't reference it`,
+                    message: `Design uses token "${tokenName}" but code doesn't reference it`,
                     suggestion: `Add token reference in code`,
                 });
             }
@@ -1680,13 +1690,16 @@ function deduplicateColors(colors) {
     }
     return Array.from(seen.values());
 }
-function generateVisualSpecsSection(node, enrichedData, variantData) {
+function generateVisualSpecsSection(node, enrichedData, variantData, varNameMap = new Map()) {
     const lines = ["", "## Token Specification", ""];
-    // Build variable name lookup from enrichment data
-    const varNameMap = new Map();
+    // Fill any gaps in the caller-supplied name map from enrichment data.
+    // enrichment entries key off variableId/variableName (NOT id/name), and only
+    // carry a useful name when it actually resolved (not the raw VariableID).
     if (enrichedData?.variables_used) {
         for (const v of enrichedData.variables_used) {
-            varNameMap.set(v.id, v.name);
+            if (v.variableId && v.variableName && v.variableName !== v.variableId && !varNameMap.has(v.variableId)) {
+                varNameMap.set(v.variableId, v.variableName);
+            }
         }
     }
     // Per-variant color token table
@@ -1740,7 +1753,7 @@ function generateVisualSpecsSection(node, enrichedData, variantData) {
     }
     // Spacing tokens with variable names
     const visualNode = resolveVisualNode(node);
-    const spacingTokens = collectSpacingTokens(visualNode);
+    const spacingTokens = collectSpacingTokens(visualNode, varNameMap);
     if (spacingTokens.length > 0) {
         lines.push("### Spacing Tokens");
         lines.push("");
@@ -2565,11 +2578,41 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                     logger.warn("Enrichment failed, proceeding without token data");
                 }
             }
-            // Build variable name lookup for per-variant color collection
+            // Build variable name lookup (id → token name) for per-variant color
+            // AND spacing collection. Two sources, in order of authority:
+            //   1. Desktop Bridge local variables (Plugin API getLocalVariablesAsync) —
+            //      works on EVERY Figma plan and is the only reliable id→name source.
+            //      The REST /files/:key/variables/local endpoint is Enterprise-only
+            //      (returns 403 on all other plans), so enrichment's variable map is
+            //      almost always empty and bound colors would otherwise render as raw
+            //      hex / raw VariableIDs.
+            //   2. Enrichment variables_used — fallback for non-bridge (Cloud/Remote)
+            //      paths. NOTE: entries key off variableId/variableName (NOT id/name),
+            //      and their name is only useful when it actually resolved to a token
+            //      name (not the raw VariableID).
             const varNameMap = new Map();
             if (enrichedData?.variables_used) {
                 for (const v of enrichedData.variables_used) {
-                    varNameMap.set(v.id, v.name);
+                    if (v.variableId && v.variableName && v.variableName !== v.variableId) {
+                        varNameMap.set(v.variableId, v.variableName);
+                    }
+                }
+            }
+            if (getDesktopConnector) {
+                try {
+                    const connector = await getDesktopConnector();
+                    const varsResult = await connector.getVariables();
+                    const varList = varsResult?.variables || varsResult?.result?.variables;
+                    if (Array.isArray(varList)) {
+                        for (const v of varList) {
+                            if (v?.id && v?.name)
+                                varNameMap.set(v.id, v.name);
+                        }
+                        logger.info({ count: varList.length }, "Resolved variable names via Desktop Bridge for docs");
+                    }
+                }
+                catch {
+                    logger.warn("Could not load bridge variables for doc token names — colors may fall back to hex");
                 }
             }
             // Collect per-variant color/icon data
@@ -2657,7 +2700,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                 }
             }
             if (s.visualSpecs) {
-                parts.push(generateVisualSpecsSection(nodeForVisual, enrichedData, variantData));
+                parts.push(generateVisualSpecsSection(nodeForVisual, enrichedData, variantData, varNameMap));
                 includedSections.push("visualSpecs");
             }
             if (s.typography) {

package/dist/cloudflare/core/design-system-manifest.js

@@ -68,12 +68,13 @@ export function searchComponents(manifest, query, options) {
     const queryLower = query.toLowerCase();
     const categoryLower = options?.category?.toLowerCase();
     const allResults = [];
-    // Search component sets first (they're typically the main design system components)
-    for (const [name, compSet] of Object.entries(manifest.componentSets)) {
-        const nameLower = name.toLowerCase();
+    // Search component sets first (they're typically the main design system components).
+    // Manifest maps are keyed by component key — always read names from the entry.
+    for (const compSet of Object.values(manifest.componentSets)) {
+        const nameLower = compSet.name.toLowerCase();
         const descLower = compSet.description?.toLowerCase() || '';
         const matchesQuery = !query || nameLower.includes(queryLower) || descLower.includes(queryLower);
-        const matchesCategory = !categoryLower || inferCategory(name).toLowerCase().includes(categoryLower);
+        const matchesCategory = !categoryLower || inferCategory(compSet.name).toLowerCase().includes(categoryLower);
         if (matchesQuery && matchesCategory) {
             allResults.push({
                 name: compSet.name,
@@ -81,17 +82,17 @@ export function searchComponents(manifest, query, options) {
                 nodeId: compSet.nodeId,
                 type: 'componentSet',
                 description: compSet.description,
-                category: inferCategory(name),
+                category: inferCategory(compSet.name),
                 variantCount: compSet.variants?.length || 0,
             });
         }
     }
     // Then search standalone components
-    for (const [name, comp] of Object.entries(manifest.components)) {
-        const nameLower = name.toLowerCase();
+    for (const comp of Object.values(manifest.components)) {
+        const nameLower = comp.name.toLowerCase();
         const descLower = comp.description?.toLowerCase() || '';
         const matchesQuery = !query || nameLower.includes(queryLower) || descLower.includes(queryLower);
-        const matchesCategory = !categoryLower || inferCategory(name).toLowerCase().includes(categoryLower);
+        const matchesCategory = !categoryLower || inferCategory(comp.name).toLowerCase().includes(categoryLower);
         if (matchesQuery && matchesCategory) {
             allResults.push({
                 name: comp.name,
@@ -99,13 +100,17 @@ export function searchComponents(manifest, query, options) {
                 nodeId: comp.nodeId,
                 type: 'component',
                 description: comp.description,
-                category: inferCategory(name),
+                category: inferCategory(comp.name),
                 defaultSize: comp.defaultSize,
             });
         }
     }
     const total = allResults.length;
-    const paginatedResults = allResults.slice(offset, offset + limit);
+    // Truncate long doc blocks in search hits — full text is available via
+    // figma_get_component_details.
+    const paginatedResults = allResults.slice(offset, offset + limit).map((r) => r.description && r.description.length > 200
+        ? { ...r, description: `${r.description.slice(0, 200)}…`, descriptionTruncated: true }
+        : r);
     const hasMore = offset + limit < total;
     return { results: paginatedResults, total, hasMore };
 }
@@ -121,14 +126,14 @@ function inferCategory(name) {
  */
 export function getCategories(manifest) {
     const categories = new Map();
-    for (const name of Object.keys(manifest.componentSets)) {
-        const cat = inferCategory(name);
+    for (const compSet of Object.values(manifest.componentSets)) {
+        const cat = inferCategory(compSet.name);
         const existing = categories.get(cat) || { componentCount: 0, componentSetCount: 0 };
         existing.componentSetCount++;
         categories.set(cat, existing);
     }
-    for (const name of Object.keys(manifest.components)) {
-        const cat = inferCategory(name);
+    for (const comp of Object.values(manifest.components)) {
+        const cat = inferCategory(comp.name);
         const existing = categories.get(cat) || { componentCount: 0, componentSetCount: 0 };
         existing.componentCount++;
         categories.set(cat, existing);

package/dist/cloudflare/core/design-system-tools.js

@@ -155,35 +155,36 @@ export function extractVisualSpec(node) {
     return hasData ? spec : undefined;
 }
 /**
- * Extract visual specs from a component node and its first-level children.
- * Returns a compact representation of the component's visual appearance.
+ * Delta-encode variant visual specs against the first variant that has one.
+ * Variants in a set share most visual properties, so repeating the full spec
+ * on every variant inflates the payload ~30x for large sets. The base variant
+ * keeps its full visualSpec; every other variant gets a visualSpecDelta with
+ * only the top-level properties that differ from the base (null means the
+ * property exists on the base but not on this variant). Variants identical to
+ * the base carry neither field.
  */
-function extractComponentVisualData(node) {
-    if (!node)
-        return {};
-    const result = {};
-    const rootSpec = extractVisualSpec(node);
-    if (rootSpec)
-        result.visualSpec = rootSpec;
-    // Extract first-level children specs (the structural elements)
-    if (node.children && Array.isArray(node.children)) {
-        const childSpecs = [];
-        for (const child of node.children) {
-            const childInfo = {
-                name: child.name,
-                type: child.type,
-            };
-            const childVisual = extractVisualSpec(child);
-            if (childVisual)
-                childInfo.visualSpec = childVisual;
-            if (child.characters)
-                childInfo.characters = child.characters;
-            childSpecs.push(childInfo);
+function deltaEncodeVariantSpecs(variants) {
+    const base = variants.find((v) => v.visualSpec);
+    if (!base)
+        return;
+    const baseSpec = base.visualSpec;
+    for (const variant of variants) {
+        if (variant === base || !variant.visualSpec)
+            continue;
+        const spec = variant.visualSpec;
+        const delta = {};
+        for (const key of new Set([...Object.keys(baseSpec), ...Object.keys(spec)])) {
+            if (!(key in spec)) {
+                delta[key] = null;
+            }
+            else if (!(key in baseSpec) || JSON.stringify(spec[key]) !== JSON.stringify(baseSpec[key])) {
+                delta[key] = spec[key];
+            }
         }
-        if (childSpecs.length > 0)
-            result.childSpecs = childSpecs;
+        delete variant.visualSpec;
+        if (Object.keys(delta).length > 0)
+            variant.visualSpecDelta = delta;
     }
-    return result;
 }
 /**
  * Resolve style node IDs to their actual visual values.
@@ -428,6 +429,7 @@ export function registerDesignSystemTools(server, getFigmaAPI, getCurrentUrl, va
         "token values per mode (light/dark), and resolved style values. " +
         "Use this instead of calling individual tools to avoid context window overflow. " +
         "Ideal for AI code generation — use visualSpec for pixel-accurate reproduction. " +
+        "Variant specs are delta-encoded: the base variant carries the full visualSpec, siblings carry visualSpecDelta with only the properties that differ. " +
         "Tokens/variables are read through the connected Desktop Bridge or cloud relay and work on ANY Figma plan — no Enterprise required. " +
         "If a tokens fetch ever reports the Variables REST API is plan-limited (403), the bridge/relay is the plan-independent path: ensure it's connected and retry rather than abandoning variables.", {
         fileKey: z
@@ -600,6 +602,9 @@ export function registerDesignSystemTools(server, getFigmaAPI, getCurrentUrl, va
                             return entry;
                         });
                         if (variants.length > 0) {
+                            // Variants share most visual properties — keep the full spec on
+                            // the base variant only and encode the rest as deltas
+                            deltaEncodeVariantSpecs(variants);
                             spec.variants = variants;
                         }
                         if (setNode?.componentPropertyDefinitions) {
@@ -611,11 +616,11 @@ export function registerDesignSystemTools(server, getFigmaAPI, getCurrentUrl, va
                                 height: setNode.absoluteBoundingBox.height,
                             };
                         }
-                        // Extract visual spec from the set node (root + children)
+                        // Extract visual spec from the set node itself
                         if (setNode) {
-                            const visualData = extractComponentVisualData(setNode);
-                            if (visualData.visualSpec) {
-                                spec.visualSpec = visualData.visualSpec;
+                            const setSpec = extractVisualSpec(setNode);
+                            if (setSpec) {
+                                spec.visualSpec = setSpec;
                             }
                         }
                         componentSpecs.push(spec);
@@ -638,11 +643,11 @@ export function registerDesignSystemTools(server, getFigmaAPI, getCurrentUrl, va
                                 height: node.absoluteBoundingBox.height,
                             };
                         }
-                        // Extract visual spec from the component node (root + children)
+                        // Extract visual spec from the component node
                         if (node) {
-                            const visualData = extractComponentVisualData(node);
-                            if (visualData.visualSpec) {
-                                spec.visualSpec = visualData.visualSpec;
+                            const nodeSpec = extractVisualSpec(node);
+                            if (nodeSpec) {
+                                spec.visualSpec = nodeSpec;
                             }
                         }
                         componentSpecs.push(spec);
@@ -762,6 +767,10 @@ export function registerDesignSystemTools(server, getFigmaAPI, getCurrentUrl, va
                     "   - layout.itemSpacing → gap\n" +
                     "   - layout.primaryAxisAlign → justify-content, counterAxisAlign → align-items\n" +
                     "   - typography → font-family, font-size, font-weight, line-height, letter-spacing\n" +
+                    "   - Variant specs are delta-encoded: one base variant carries the full visualSpec; " +
+                    "sibling variants carry 'visualSpecDelta' with ONLY the properties that differ from the base " +
+                    "(null = property absent on this variant). Merge base visualSpec + visualSpecDelta to get a " +
+                    "variant's full spec. A variant with neither field is visually identical to the base.\n" +
                     "3. Do NOT add decorative elements (colored borders, accents, dividers, gradients) " +
                     "unless they appear in the visualSpec data.\n" +
                     "4. Use 'imageUrl' screenshots as the visual ground truth. If the screenshot " +

package/dist/cloudflare/core/diagnose-tool.js

@@ -34,6 +34,10 @@ function buildReport(opts) {
         if (plugin.editorType && plugin.editorType !== "figma") {
             lines.push(`- Editor type: ${plugin.editorType}.`);
         }
+        if (plugin.pluginUpdateAvailable) {
+            const bundledVersion = opts.getBundledPluginVersion?.() ?? opts.getServerVersion();
+            lines.push(`- ⚠️ **Plugin update available**: the imported plugin${plugin.pluginVersion ? ` (v${plugin.pluginVersion})` : " (version unknown — very old)"} differs from the plugin files this server ships (v${bundledVersion}). Figma caches plugin files, so re-import it: Figma Desktop → Plugins → Development → Import plugin from manifest → select manifest.json. Until then, recently added or fixed plugin features may silently misbehave.`);
+        }
     }
     else {
         lines.push(`- ⚠️ Desktop Bridge plugin not connected${plugin.port ? ` (server is listening on port ${plugin.port})` : ""}.`);

package/dist/cloudflare/core/enrichment/enrichment-service.js

@@ -83,17 +83,23 @@ export class EnrichmentService {
                 const enriched = {
                     ...variable,
                 };
-                // Resolve values for all modes
+                // Resolve values for all modes — each mode must resolve ITS OWN
+                // value, so the modeId is threaded through the resolver (which
+                // also keys its cache per mode).
                 if (options.include_exports !== false) {
                     const resolved_values = {};
-                    for (const [modeId, value] of Object.entries(variable.valuesByMode || {})) {
-                        const resolvedValue = await this.styleResolver.resolveVariableValue(variable, variablesMap, options.max_depth);
+                    for (const modeId of Object.keys(variable.valuesByMode || {})) {
+                        const resolvedValue = await this.styleResolver.resolveVariableValue(variable, variablesMap, options.max_depth, 0, modeId);
                         resolved_values[modeId] = resolvedValue;
                     }
                     enriched.resolved_values = resolved_values;
-                    // Generate export formats using first mode
+                    // Generate export formats using first mode. Guard only against
+                    // null/undefined — legitimate falsy values (0, false, "") must
+                    // still produce export formats.
                     const firstModeValue = Object.values(resolved_values)[0];
-                    if (firstModeValue && options.export_formats) {
+                    if (firstModeValue !== null &&
+                        firstModeValue !== undefined &&
+                        options.export_formats) {
                         enriched.export_formats = this.styleResolver.generateExportFormats(variable.name, firstModeValue, variable.resolvedType, options.export_formats);
                     }
                 }