figma-console-mcp 1.32.0 → 1.33.0

package/README.md

@@ -8,7 +8,7 @@
 
 > **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)
+> **🆕 Self-healing connection + 33-fix audit (v1.33.0):** The Desktop Bridge now tells the truth and heals itself — the status pill derives from live connection state (it used to glow green with zero MCP servers connected), `/health` auto-discovery reconnects restarted servers without the manual ritual, and a version handshake banners the plugin when it needs a re-import. Underneath: 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. **Re-import the plugin manifest one more time** — the new handshake makes it the last one you have to discover on your own. [See what's new →](CHANGELOG.md#1330---2026-07-02)
 
 ## What is this?
 
@@ -808,9 +808,11 @@ 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.33.0 (Stable) - Production-ready. Latest: connection UX overhaul (honest status pill derived from live connection state, `/health` auto-discovery with self-healing reconnect, version handshake with in-plugin re-import banner) + 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, **106 tools** (Local) / **95 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [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.
@@ -838,7 +840,6 @@ The architecture supports adding new apps with minimal boilerplate — each app
 - [ ] **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.
 - [ ] **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/accessibility-tools.js

@@ -242,11 +242,58 @@ function formatAxeResults(axeResults) {
         inapplicable: axeResults.inapplicable?.length || 0,
     };
 }
+/**
+ * Heuristic WCAG 1.4.12 (Text Spacing) / 1.4.4 (Resize Text) signal for CODE.
+ *
+ * This is where text-spacing override support actually belongs: 1.4.12 is about whether
+ * content survives a USER overriding line/letter/word/paragraph spacing — it cannot be
+ * proven from a design's spacing value, only from the code. axe-core can't evaluate it
+ * (it needs layout), but the common, checkable risk indicator is fixed-px typography:
+ * line-height/font-size locked in px don't respond to spacing overrides or text-only zoom,
+ * whereas unitless line-height and rem/em sizing do. Surfaces fixed-px usage as an advisory
+ * (info) finding so teams verify reflow — without red-flagging sub-1.5 line heights, which
+ * are not failures.
+ */
+function scanTextSpacingSupport(html) {
+    // Collect CSS from <style> blocks and inline style="" attributes
+    let css = "";
+    const styleBlocks = html.match(/<style[^>]*>([\s\S]*?)<\/style>/gi) || [];
+    for (const block of styleBlocks)
+        css += block.replace(/<\/?style[^>]*>/gi, "") + "\n";
+    const inlineStyles = html.match(/style=["']([^"']*)["']/gi) || [];
+    for (const s of inlineStyles)
+        css += s.replace(/^style=["']|["']$/gi, "") + ";\n";
+    if (!css.trim())
+        return null;
+    // line-height: <n>px  → won't grow when a user overrides text spacing (1.4.12 risk)
+    const pxLineHeights = css.match(/line-height\s*:\s*[\d.]+px/gi) || [];
+    // font-size: <n>px → won't scale on text-only zoom / 200% resize (1.4.4 risk)
+    const pxFontSizes = css.match(/font-size\s*:\s*[\d.]+px/gi) || [];
+    if (pxLineHeights.length === 0 && pxFontSizes.length === 0)
+        return null;
+    const samples = [
+        ...pxLineHeights.slice(0, 5).map((m) => m.trim()),
+        ...pxFontSizes.slice(0, 5).map((m) => m.trim()),
+    ];
+    return {
+        rule: "text-spacing-support",
+        severity: "info",
+        count: pxLineHeights.length + pxFontSizes.length,
+        description: `Typography uses fixed px units (${pxLineHeights.length} px line-height, ${pxFontSizes.length} px font-size). ` +
+            "This is where WCAG 1.4.12 (Text Spacing) and 1.4.4 (Resize Text) are actually verified — not on the design side. " +
+            "Prefer unitless line-height (e.g. line-height: 1.4) and rem/em font sizes so user spacing overrides and text-only zoom do not clip or overlap content. " +
+            "Advisory only: a sub-1.5 line height is NOT a failure — confirm content still reflows when the 1.4.12 text-spacing overrides are applied.",
+        wcagTags: ["wcag22aa", "wcag1412", "wcag144"],
+        helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html",
+        samples,
+    };
+}
 export function registerAccessibilityTools(server) {
     server.tool("figma_scan_code_accessibility", "Scan HTML code for accessibility violations using axe-core (Deque). " +
         "Runs structural/semantic checks via JSDOM: ARIA attributes, roles, labels, alt text, " +
         "form labels, heading order, landmarks, semantic HTML, tabindex, duplicate IDs, lang attribute, and ~50 more rules. " +
         "Visual checks (color contrast, focus visibility) are disabled in this mode — use figma_lint_design for visual a11y on the design side. " +
+        "Also surfaces a WCAG 1.4.12 (Text Spacing) / 1.4.4 (Resize Text) advisory when typography is locked to fixed px units — the code side is where text-spacing override support is actually verified (a sub-1.5 line height in a design is not itself a failure). " +
         "Together, these two tools provide full-spectrum accessibility coverage across design and code. " +
         "Pass component HTML directly or use with figma_check_design_parity for design-to-code a11y comparison. " +
         "No Figma connection required — this is a standalone code analysis tool.", {
@@ -264,6 +311,14 @@ export function registerAccessibilityTools(server) {
                 context: context || undefined,
             });
             const formatted = formatAxeResults(axeResults);
+            // Supplementary WCAG 1.4.12 / 1.4.4 advisory — axe can't see layout/overrides,
+            // and this (not the design side) is where text-spacing support is verifiable.
+            const textSpacing = scanTextSpacingSupport(html);
+            if (textSpacing) {
+                formatted.categories.push(textSpacing);
+                formatted.summary.info += textSpacing.count;
+                formatted.summary.total += textSpacing.count;
+            }
             // Optionally strip pass/incomplete counts to save tokens
             if (!includePassingRules) {
                 delete formatted.passes;

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

@@ -222,6 +222,8 @@ export class CloudWebSocketConnector {
                 params.fontWeight = options.fontWeight;
             if (options.fontFamily)
                 params.fontFamily = options.fontFamily;
+            if (options.fontStyle)
+                params.fontStyle = options.fontStyle;
         }
         return this.sendCommand('SET_TEXT_CONTENT', params);
     }

package/dist/cloudflare/core/deep-component-tools.js

@@ -78,7 +78,7 @@ export function registerDeepComponentTools(server, getDesktopConnector) {
     // -----------------------------------------------------------------------
     // Tool: figma_analyze_component_set
     // -----------------------------------------------------------------------
-    server.tool("figma_analyze_component_set", "Analyze a Figma COMPONENT_SET to extract variant state machine and cross-variant diffs for code generation. Returns: (1) variant axes (size, state) with all values, (2) CSS pseudo-class mappings for interaction states (hover→:hover, focus→:focus-visible, disabled→:disabled, error→[aria-invalid]), (3) visual diff from default state per variant (only changed properties — fill token, stroke token, stroke weight, text color, opacity, effects, visibility), (4) component property definitions mapped to code props (BOOLEAN→boolean, TEXT→string, INSTANCE_SWAP→slot/ReactNode). Use this on the parent COMPONENT_SET node, not individual variants. Requires Desktop Bridge plugin.", {
+    server.tool("figma_analyze_component_set", "Analyze a Figma COMPONENT_SET to extract variant state machine and cross-variant diffs for code generation. Returns: (1) variant axes (size, state) with all values, (2) CSS pseudo-class mappings for interaction states (hover→:hover, focus→:focus-visible, disabled→:disabled, error→[aria-invalid]), (3) visual diff from default state per variant (only changed properties — fill token, stroke token, stroke weight, text color, opacity, effects, visibility), (4) component property definitions mapped to code props (BOOLEAN→boolean, TEXT→string, INSTANCE_SWAP→slot/ReactNode), and (5) slots — Figma SLOT properties (name, preferredValues = the components a slot accepts, and limitViolations) to implement as named slots / children props (React {children} or named ReactNode; Web Components <slot name>). Use this on the parent COMPONENT_SET node, not individual variants. Requires Desktop Bridge plugin.", {
         nodeId: z
             .string()
             .describe("COMPONENT_SET node ID (the parent of all variants, e.g., '214:274')"),

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,9 @@ function buildReport(opts) {
         if (plugin.editorType && plugin.editorType !== "figma") {
             lines.push(`- Editor type: ${plugin.editorType}.`);
         }
+        if (plugin.pluginUpdateAvailable) {
+            lines.push(`- ⚠️ **Plugin update available**: the imported plugin${plugin.pluginVersion ? ` (v${plugin.pluginVersion})` : " (version unknown — very old)"} is older than this server (v${opts.getServerVersion()}). 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);
                     }
                 }

package/dist/cloudflare/core/enrichment/style-resolver.js

@@ -56,29 +56,38 @@ export class StyleValueResolver {
         }
     }
     /**
-     * Resolve a variable's value, handling alias chains
+     * Resolve a variable's value, handling alias chains.
+     *
+     * `modeId` selects which mode's value to resolve; omitted, it falls back
+     * to the variable's first mode (legacy behavior for callers that don't
+     * care about modes). The cache is keyed per (variable, mode) so
+     * multi-mode variables don't all resolve to the first mode's value.
      */
-    async resolveVariableValue(variable, allVariables, maxDepth = 10, currentDepth = 0) {
+    async resolveVariableValue(variable, allVariables, maxDepth = 10, currentDepth = 0, modeId) {
         if (currentDepth >= maxDepth) {
             this.logger.warn({
                 variable: variable.name,
             }, "Max resolution depth reached");
             return null;
         }
-        const cacheKey = `var:${variable.id}`;
+        // Pick the mode to resolve: the requested modeId when this variable
+        // has a value for it, otherwise the first available mode (alias
+        // targets in other collections have different modeIds).
+        const modes = Object.keys(variable.valuesByMode || {});
+        if (modes.length === 0) {
+            return null;
+        }
+        const effectiveMode = modeId !== undefined && variable.valuesByMode[modeId] !== undefined
+            ? modeId
+            : modes[0];
+        const cacheKey = `var:${variable.id}:${effectiveMode}`;
         if (this.variableCache.has(cacheKey)) {
             return this.variableCache.get(cacheKey);
         }
         try {
-            // Get the value for the default mode (or first available mode)
-            const modes = Object.keys(variable.valuesByMode || {});
-            if (modes.length === 0) {
-                return null;
-            }
-            const defaultMode = modes[0]; // TODO: Support mode selection
-            const value = variable.valuesByMode[defaultMode];
+            const value = variable.valuesByMode[effectiveMode];
             // Check if this is an alias (reference to another variable)
-            if (typeof value === "object" && value.type === "VARIABLE_ALIAS") {
+            if (value !== null && typeof value === "object" && value.type === "VARIABLE_ALIAS") {
                 const targetVariable = allVariables.get(value.id);
                 if (!targetVariable) {
                     this.logger.warn({
@@ -87,8 +96,9 @@ export class StyleValueResolver {
                     }, "Variable alias target not found");
                     return null;
                 }
-                // Recursively resolve the alias
-                const resolvedValue = await this.resolveVariableValue(targetVariable, allVariables, maxDepth, currentDepth + 1);
+                // Recursively resolve the alias, carrying the requested modeId
+                // through so same-collection targets resolve the same mode.
+                const resolvedValue = await this.resolveVariableValue(targetVariable, allVariables, maxDepth, currentDepth + 1, modeId);
                 this.variableCache.set(cacheKey, resolvedValue);
                 return resolvedValue;
             }
@@ -109,7 +119,9 @@ export class StyleValueResolver {
      * Format a variable value based on its type
      */
     formatVariableValue(value, type) {
-        if (!value)
+        // Guard only null/undefined — 0, false, and "" are legitimate
+        // variable values (opacity 0, boolean flags off, empty strings).
+        if (value === null || value === undefined)
             return null;
         switch (type) {
             case "COLOR":
@@ -133,10 +145,18 @@ export class StyleValueResolver {
             return color;
         }
         if (color.r !== undefined && color.g !== undefined && color.b !== undefined) {
-            const r = Math.round(color.r * 255);
-            const g = Math.round(color.g * 255);
-            const b = Math.round(color.b * 255);
-            return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`.toUpperCase();
+            const clampByte = (f) => Math.max(0, Math.min(255, Math.round(f * 255)));
+            const toHex = (byte) => byte.toString(16).padStart(2, "0");
+            const r = clampByte(color.r);
+            const g = clampByte(color.g);
+            const b = clampByte(color.b);
+            let hex = `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+            // Preserve alpha: append the alpha byte for semi-transparent colors
+            // (mirrors rgbaToHex in tokens/figma-converter.ts).
+            if (color.a !== undefined && color.a < 1) {
+                hex += toHex(clampByte(color.a));
+            }
+            return hex.toUpperCase();
         }
         return null;
     }