figma-console-mcp 1.40.0 → 1.40.2

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

@@ -283,11 +283,97 @@ export function parseComponentDescription(description) {
     result.overview = overviewLines.join(" ").trim();
     return result;
 }
+/** Strip Figma's internal "#123:4" id suffix from a component property name */
+function stripPropertyIdSuffix(rawName) {
+    return rawName.replace(/#\d+:\d+$/, "").trim();
+}
+/**
+ * Human-readable name of the main component behind an instance/component id.
+ * Variants resolve to "Set name (Value / Value)" since a bare "Size=16" is useless.
+ */
+export function resolveMainComponentName(componentId, lookup = {}) {
+    if (!componentId)
+        return undefined;
+    const comp = lookup.components?.[componentId];
+    if (!comp?.name)
+        return undefined;
+    const setName = comp.componentSetId ? lookup.componentSets?.[comp.componentSetId]?.name : undefined;
+    if (setName)
+        return `${setName} (${cleanVariantName(comp.name)})`;
+    return comp.name;
+}
+/** Largest dimension (px) an instance-swap slot can have and still be treated as an icon */
+const MAX_ICON_SLOT_SIZE = 64;
+/**
+ * Decide whether an INSTANCE is an icon, and name it.
+ * Signals, any of which qualifies:
+ *   - the layer name or the MAIN COMPONENT name mentions "icon"
+ *   - the instance is driven by an INSTANCE_SWAP property and is icon-sized —
+ *     covers slots with neutral layer names like "Leading Modifier"
+ * The reported name is the main component (what's actually in the slot) when it
+ * can be resolved, falling back to the cleaned layer name.
+ */
+function detectIconInstance(node, lookup) {
+    if (node.type !== "INSTANCE")
+        return null;
+    const layerName = node.name || "";
+    const mainName = resolveMainComponentName(node.componentId, lookup);
+    const swapRef = node.componentPropertyReferences?.mainComponent;
+    const swapProperty = typeof swapRef === "string" ? stripPropertyIdSuffix(swapRef) : undefined;
+    const box = node.absoluteBoundingBox || node.size;
+    const width = box?.width ?? box?.x;
+    const height = box?.height ?? box?.y;
+    const iconSized = typeof width !== "number" || typeof height !== "number"
+        ? true
+        : Math.max(width, height) <= MAX_ICON_SLOT_SIZE;
+    const nameSaysIcon = /icon/i.test(layerName) || (mainName ? /icon/i.test(mainName) : false);
+    if (!nameSaysIcon && !(swapProperty && iconSized))
+        return null;
+    const cleanedLayerName = layerName.replace(/^icon\s*\/?\s*/i, "").trim() || layerName;
+    return {
+        name: mainName || cleanedLayerName,
+        type: "instance",
+        layerName,
+        ...(swapProperty ? { swapProperty } : {}),
+    };
+}
+/** True when the node has at least one visible solid fill */
+function hasVisibleSolidFill(node) {
+    return Array.isArray(node?.fills)
+        && node.fills.some((f) => f.type === "SOLID" && f.color && f.visible !== false);
+}
+/**
+ * When a variant's root is transparent, some systems paint the surface with a
+ * dedicated full-bleed layer instead. Returns that layer: a visible, non-text,
+ * non-instance direct child that covers the root's bounds (±1px) and has a
+ * solid fill. Anything smaller (an icon, a dot, a divider) is NOT a background.
+ */
+function findBackgroundLayer(root) {
+    if (hasVisibleSolidFill(root))
+        return null;
+    const rootBox = root.absoluteBoundingBox;
+    if (!rootBox || !Array.isArray(root.children))
+        return null;
+    for (const child of root.children) {
+        if (child.visible === false || child.type === "TEXT" || child.type === "INSTANCE")
+            continue;
+        const box = child.absoluteBoundingBox;
+        if (!box || !hasVisibleSolidFill(child))
+            continue;
+        const covers = Math.abs(box.x - rootBox.x) <= 1
+            && Math.abs(box.y - rootBox.y) <= 1
+            && Math.abs(box.width - rootBox.width) <= 1
+            && Math.abs(box.height - rootBox.height) <= 1;
+        if (covers)
+            return child;
+    }
+    return null;
+}
 /**
  * Collect color data from all variants in a COMPONENT_SET.
  * For single COMPONENTs, returns data for just that component.
  */
-export function collectAllVariantData(node, varNameMap) {
+export function collectAllVariantData(node, varNameMap, lookup = {}) {
     const variants = [];
     const nodesToWalk = node.type === "COMPONENT_SET" && node.children?.length > 0
         ? node.children
@@ -296,44 +382,64 @@ export function collectAllVariantData(node, varNameMap) {
         const data = {
             variantName: variant.name || "Default",
             fills: [],
+            descendantFills: [],
+            iconColors: [],
             strokes: [],
             textColors: [],
             icons: [],
         };
-        walkVariantNode(variant, data, varNameMap, 0, 5);
+        const backgroundLayer = findBackgroundLayer(variant);
+        if (backgroundLayer)
+            data.backgroundLayer = backgroundLayer.name || "background layer";
+        walkVariantNode(variant, data, { varNameMap, lookup, backgroundLayer }, 0, 5, null);
         variants.push(data);
     }
     return variants;
 }
 /** Walk a single variant node tree to collect colors and icons */
-function walkVariantNode(node, data, varNameMap, depth, maxDepth) {
+function walkVariantNode(node, data, ctx, depth, maxDepth, 
+/** Label of the icon instance we're inside of, or null when outside any icon */
+insideIcon) {
     if (depth > maxDepth)
         return;
     const isText = node.type === "TEXT";
-    // Check if this is an icon instance
-    if (node.type === "INSTANCE" && (node.name?.toLowerCase().includes("icon") ||
-        node.name?.toLowerCase().startsWith("icon"))) {
-        const iconName = node.name.replace(/^icon\s*\/?\s*/i, "").trim();
-        data.icons.push({ name: iconName || node.name, type: "instance" });
-    }
-    // Collect fills
+    // Icons are reported once, at the outermost instance — everything beneath it
+    // (vectors, nested instances) is that icon's artwork, not a separate icon.
+    if (insideIcon === null) {
+        const icon = detectIconInstance(node, ctx.lookup);
+        if (icon) {
+            data.icons.push(icon);
+            insideIcon = icon.layerName || icon.name;
+        }
+    }
+    const toEntry = (paint) => {
+        const varId = paint.boundVariables?.color?.id;
+        return {
+            hex: figmaRGBAToHex({ ...paint.color, a: paint.opacity ?? paint.color.a ?? 1 }),
+            nodeName: node.name || "",
+            variableId: varId,
+            variableName: varId ? ctx.varNameMap.get(varId) : undefined,
+        };
+    };
+    // Collect fills. Only the variant root (or its full-bleed stand-in) is a
+    // BACKGROUND — a descendant's fill must never be promoted to one, or a
+    // transparent variant gets documented with its icon's color as the surface.
     if (node.fills && Array.isArray(node.fills)) {
         for (const fill of node.fills) {
             if (fill.type === "SOLID" && fill.color && fill.visible !== false) {
-                const hex = figmaRGBAToHex({ ...fill.color, a: fill.opacity ?? fill.color.a ?? 1 });
-                const varId = fill.boundVariables?.color?.id;
-                const entry = {
-                    hex,
-                    nodeName: node.name || "",
-                    variableId: varId,
-                    variableName: varId ? varNameMap.get(varId) : undefined,
-                };
+                const entry = toEntry(fill);
                 if (isText) {
                     data.textColors.push(entry);
                 }
-                else {
+                else if (insideIcon !== null) {
+                    data.iconColors.push({ ...entry, iconLabel: insideIcon });
+                }
+                else if (depth === 0 || node === ctx.backgroundLayer) {
                     data.fills.push(entry);
                 }
+                else {
+                    data.descendantFills.push(entry);
+                }
             }
         }
     }
@@ -341,21 +447,20 @@ function walkVariantNode(node, data, varNameMap, depth, maxDepth) {
     if (node.strokes && Array.isArray(node.strokes)) {
         for (const stroke of node.strokes) {
             if (stroke.type === "SOLID" && stroke.color && stroke.visible !== false) {
-                const hex = figmaRGBAToHex({ ...stroke.color, a: stroke.opacity ?? stroke.color.a ?? 1 });
-                const varId = stroke.boundVariables?.color?.id;
-                data.strokes.push({
-                    hex,
-                    nodeName: node.name || "",
-                    variableId: varId,
-                    variableName: varId ? varNameMap.get(varId) : undefined,
-                });
+                const entry = toEntry(stroke);
+                if (insideIcon !== null) {
+                    data.iconColors.push({ ...entry, iconLabel: insideIcon });
+                }
+                else {
+                    data.strokes.push(entry);
+                }
             }
         }
     }
     // Recurse into children
     if (node.children && Array.isArray(node.children)) {
         for (const child of node.children) {
-            walkVariantNode(child, data, varNameMap, depth + 1, maxDepth);
+            walkVariantNode(child, data, ctx, depth + 1, maxDepth, insideIcon);
         }
     }
 }
@@ -510,6 +615,159 @@ function collectSpacingTokens(node, varNameMap = new Map()) {
     }
     return tokens;
 }
+/** Parse "Size=lg, State=hover" into ordered [property, value] pairs */
+export function parseVariantProperties(rawName) {
+    const pairs = [];
+    for (const part of (rawName || "").split(",")) {
+        const eqIdx = part.indexOf("=");
+        if (eqIdx <= 0)
+            continue;
+        pairs.push([part.slice(0, eqIdx).trim(), part.slice(eqIdx + 1).trim()]);
+    }
+    return pairs;
+}
+const SPACING_COMPARISON_PROPS = [
+    { key: "paddingTop", label: "Padding top" },
+    { key: "paddingRight", label: "Padding right" },
+    { key: "paddingBottom", label: "Padding bottom" },
+    { key: "paddingLeft", label: "Padding left" },
+    { key: "itemSpacing", label: "Gap" },
+    { key: "cornerRadius", label: "Border radius" },
+    { key: "strokeWeight", label: "Border width" },
+];
+/** Cap on variant names spelled out in a single note, so 100-variant sets stay readable */
+const MAX_NAMED_VARIANTS = 5;
+function formatSpacingValue(value) {
+    return typeof value === "number" ? `${value}px` : value;
+}
+/**
+ * Compare spacing across EVERY variant of a COMPONENT_SET instead of reporting
+ * the first child as if it spoke for the whole set.
+ *
+ *   - all variants agree            → one plain row, same as a single component
+ *   - they differ along one variant
+ *     property (e.g. Size)          → "varies by Size: sm 4px · md 8px"
+ *   - they differ with no pattern   → "varies: 0px ×8, 55px (Primary / Default)"
+ *
+ * Separately flags any property bound to a variable on some variants and left
+ * hardcoded on others with NO variant property accounting for the split — a
+ * reliable fingerprint of an accidental edit.
+ *
+ * The REST API omits zero-valued spacing fields, so a property missing on one
+ * variant but present on another is compared as 0, not skipped.
+ */
+export function collectSpacingAcrossVariants(setNode, varNameMap = new Map()) {
+    const variants = Array.isArray(setNode?.children) ? setNode.children : [];
+    const result = { variantCount: variants.length, rows: [], inconsistencies: [] };
+    if (variants.length === 0)
+        return result;
+    for (const { key, label } of SPACING_COMPARISON_PROPS) {
+        const isSet = (v) => (v[key] !== undefined && v[key] !== null)
+            // Per-corner rounding: REST drops the scalar and sends only the 4-tuple
+            || (key === "cornerRadius" && Array.isArray(v.rectangleCornerRadii));
+        if (!variants.some(isSet))
+            continue;
+        const samples = variants.map((v) => {
+            let value = v[key] ?? 0;
+            // Per-corner radii: `cornerRadius` is absent and the 4-tuple carries the values
+            if (key === "cornerRadius" && (v[key] === undefined || v[key] === null) && Array.isArray(v.rectangleCornerRadii)) {
+                value = v.rectangleCornerRadii.map((r) => `${r}px`).join(" / ");
+            }
+            const varId = typeof v.boundVariables?.[key]?.id === "string"
+                ? v.boundVariables[key].id
+                : undefined;
+            return {
+                displayName: cleanVariantName(v.name || "Unknown"),
+                props: parseVariantProperties(v.name || ""),
+                value,
+                variableName: varId ? varNameMap.get(varId) || varId : undefined,
+                signature: `${value}|${varId ?? ""}`,
+                display: "",
+            };
+        });
+        const signatures = new Set(samples.map((x) => x.signature));
+        if (signatures.size === 1) {
+            const only = samples[0];
+            result.rows.push({
+                property: label,
+                uniform: true,
+                variableCell: only.variableName ? `\`${only.variableName}\`` : "—",
+                valueCell: formatSpacingValue(only.value),
+            });
+            continue;
+        }
+        // Variable cell: every distinct token in play, plus a marker when some variants have none
+        const variableNames = [...new Set(samples.map((x) => x.variableName).filter((n) => !!n))];
+        const bound = samples.filter((x) => x.variableName);
+        const unbound = samples.filter((x) => !x.variableName);
+        const variableParts = variableNames.map((n) => `\`${n}\``);
+        if (bound.length > 0 && unbound.length > 0)
+            variableParts.push("unbound");
+        const variableCell = variableParts.length > 0 ? variableParts.join(", ") : "—";
+        // Two variants can share a pixel value yet bind different tokens. When the
+        // binding is part of what varies, show it next to the value — otherwise
+        // "sm 8px · lg 8px" reads as a contradiction.
+        const bindingVaries = variableNames.length > 1 || (bound.length > 0 && unbound.length > 0);
+        for (const x of samples) {
+            x.display = bindingVaries
+                ? `${formatSpacingValue(x.value)} (${x.variableName ? `\`${x.variableName}\`` : "unbound"})`
+                : formatSpacingValue(x.value);
+        }
+        // Is the variation fully explained by ONE variant property (e.g. Size)?
+        let explainedBy = null;
+        let explainedGroups = [];
+        for (const [propName] of samples[0].props) {
+            const groups = new Map();
+            for (const x of samples) {
+                const propValue = x.props.find(([n]) => n === propName)?.[1];
+                if (propValue === undefined) {
+                    groups.clear();
+                    break;
+                }
+                if (!groups.has(propValue))
+                    groups.set(propValue, new Set());
+                groups.get(propValue).add(x.display);
+            }
+            // groups.size < samples.length: with one variant per group the "explanation"
+            // is vacuous — any values at all would satisfy it (single-property sets).
+            if (groups.size > 1 && groups.size < samples.length && [...groups.values()].every((vals) => vals.size === 1)) {
+                explainedBy = propName;
+                explainedGroups = [...groups.entries()].map(([pv, vals]) => [pv, [...vals][0]]);
+                break;
+            }
+        }
+        let valueCell;
+        if (explainedBy) {
+            valueCell = `varies by **${explainedBy}**: ${explainedGroups.map(([pv, val]) => `${pv} ${val}`).join(" · ")}`;
+        }
+        else {
+            // No pattern — list each distinct value, most common first, naming the rare ones
+            const byValue = new Map();
+            for (const x of samples) {
+                if (!byValue.has(x.display))
+                    byValue.set(x.display, []);
+                byValue.get(x.display).push(x.displayName);
+            }
+            const parts = [...byValue.entries()]
+                .sort((a, b) => b[1].length - a[1].length)
+                .map(([val, names]) => names.length <= 2 ? `${val} — ${names.join(", ")}` : `${val} ×${names.length}`);
+            valueCell = `varies: ${parts.join(", ")}`;
+        }
+        result.rows.push({ property: label, uniform: false, variableCell, valueCell });
+        // Only an UNEXPLAINED binding split is suspicious. When a variant property
+        // accounts for it (a "Dot" shape that has no padding at all), it's a design
+        // decision — the table row already shows it, and flagging it would be noise.
+        if (bound.length > 0 && unbound.length > 0 && !explainedBy) {
+            const named = unbound
+                .slice(0, MAX_NAMED_VARIANTS)
+                .map((x) => `${x.displayName} (${formatSpacingValue(x.value)})`)
+                .join(", ");
+            const more = unbound.length > MAX_NAMED_VARIANTS ? `, +${unbound.length - MAX_NAMED_VARIANTS} more` : "";
+            result.inconsistencies.push(`**${label}** is bound to ${variableNames.map((n) => `\`${n}\``).join(", ")} on ${bound.length} of ${samples.length} variants but hardcoded on ${unbound.length}: ${named}${more}.`);
+        }
+    }
+    return result;
+}
 // ============================================================================
 // Component Set Resolution Helpers
 // ============================================================================
@@ -1546,7 +1804,13 @@ function generateOverviewSection(componentName, description, fileUrl, parsedDesc
     }
     return lines.join("\n");
 }
-function generateStatesAndVariantsSection(node, variantData) {
+/** Icon cell text: the icon in the slot, flagged when it's only an instance-swap default */
+function formatIconCell(icon) {
+    if (!icon)
+        return "—";
+    return icon.swapProperty ? `${icon.name} _(default — swappable via **${icon.swapProperty}**)_` : icon.name;
+}
+export function generateStatesAndVariantsSection(node, variantData, lookup = {}) {
     const props = node.componentPropertyDefinitions;
     if (!props || Object.keys(props).length === 0)
         return "";
@@ -1554,9 +1818,10 @@ function generateStatesAndVariantsSection(node, variantData) {
     const variants = [];
     const booleans = [];
     const textProps = [];
+    const instanceSwaps = [];
     for (const [rawName, def] of Object.entries(props)) {
         // Strip Figma internal ID suffixes like "#17100:0" from property names
-        const name = rawName.replace(/#\d+:\d+$/, "").trim();
+        const name = stripPropertyIdSuffix(rawName);
         if (def.type === "VARIANT") {
             variants.push({
                 name,
@@ -1570,6 +1835,14 @@ function generateStatesAndVariantsSection(node, variantData) {
         else if (def.type === "TEXT") {
             textProps.push({ name, defaultValue: def.defaultValue || "" });
         }
+        else if (def.type === "INSTANCE_SWAP") {
+            // defaultValue is the default component's node id — name it when we can
+            instanceSwaps.push({
+                name,
+                defaultName: resolveMainComponentName(def.defaultValue, lookup) ?? null,
+                preferredCount: Array.isArray(def.preferredValues) ? def.preferredValues.length : 0,
+            });
+        }
     }
     // Variant matrix with per-variant color data
     if (variants.length > 0 && variantData && variantData.length > 0) {
@@ -1577,8 +1850,10 @@ function generateStatesAndVariantsSection(node, variantData) {
         lines.push("");
         // Determine which columns to show based on available data
         const hasIcons = variantData.some((v) => v.icons.length > 0);
-        const hasFills = variantData.some((v) => v.fills.length > 0);
-        if (hasFills || hasIcons) {
+        // Any color at all earns the matrix — a set of transparent (outline/ghost)
+        // variants still has text and icon colors worth tabulating.
+        const hasColors = variantData.some((v) => v.fills.length > 0 || v.textColors.length > 0 || v.iconColors.length > 0 || v.strokes.length > 0);
+        if (hasColors || hasIcons) {
             const headerParts = ["Variant", "Background"];
             if (hasIcons)
                 headerParts.push("Icon");
@@ -1597,14 +1872,13 @@ function generateStatesAndVariantsSection(node, variantData) {
                     ? (bgFill.variableName ? `\`${bgFill.variableName}\` (${bgFill.hex})` : bgFill.hex)
                     : "—";
                 // Get primary text/icon color
-                const textColor = vd.textColors[0] || vd.strokes[0];
+                const textColor = vd.textColors[0] || vd.iconColors[0] || vd.strokes[0];
                 const textVal = textColor
                     ? (textColor.variableName ? `\`${textColor.variableName}\` (${textColor.hex})` : textColor.hex)
                     : "—";
                 const rowParts = [`**${displayName}**`, bgVal];
                 if (hasIcons) {
-                    const icon = vd.icons[0]?.name || "—";
-                    rowParts.push(icon);
+                    rowParts.push(formatIconCell(vd.icons[0]));
                 }
                 rowParts.push(textVal);
                 lines.push("| " + rowParts.join(" | ") + " |");
@@ -1619,8 +1893,7 @@ function generateStatesAndVariantsSection(node, variantData) {
             lines.push("|---------|---------------------|");
             for (const vd of variantData) {
                 const displayName = cleanVariantName(vd.variantName);
-                const icon = vd.icons[0]?.name || "—";
-                lines.push(`| ${displayName} | ${icon} |`);
+                lines.push(`| ${displayName} | ${formatIconCell(vd.icons[0])} |`);
             }
             lines.push("");
         }
@@ -1635,7 +1908,7 @@ function generateStatesAndVariantsSection(node, variantData) {
         lines.push("");
     }
     // Configurable properties table (all property types)
-    if (booleans.length > 0 || textProps.length > 0) {
+    if (booleans.length > 0 || textProps.length > 0 || instanceSwaps.length > 0) {
         lines.push("### Configurable Properties");
         lines.push("");
         lines.push("| Property | Type | Default | Description |");
@@ -1649,6 +1922,10 @@ function generateStatesAndVariantsSection(node, variantData) {
         for (const t of textProps) {
             lines.push(`| **${t.name}** | \`string\` | \`"${t.defaultValue}"\` | Sets ${t.name.toLowerCase()} content |`);
         }
+        for (const sw of instanceSwaps) {
+            const preferred = sw.preferredCount > 0 ? ` (${sw.preferredCount} preferred values)` : "";
+            lines.push(`| **${sw.name}** | \`instance swap\` | ${sw.defaultName ? `\`${sw.defaultName}\`` : "—"} | Swaps the nested ${sw.name.toLowerCase()} instance${preferred} |`);
+        }
         lines.push("");
     }
     return lines.join("\n");
@@ -1712,7 +1989,9 @@ function deduplicateColors(colors) {
     }
     return Array.from(seen.values());
 }
-function generateVisualSpecsSection(node, enrichedData, variantData, varNameMap = new Map()) {
+export function generateVisualSpecsSection(node, enrichedData, variantData, varNameMap = new Map(), 
+/** The full COMPONENT_SET when `node` is its default variant — enables cross-variant spacing comparison */
+setNode) {
     const lines = ["", "## Token Specification", ""];
     // Fill any gaps in the caller-supplied name map from enrichment data.
     // enrichment entries key off variableId/variableName (NOT id/name), and only
@@ -1731,15 +2010,37 @@ function generateVisualSpecsSection(node, enrichedData, variantData, varNameMap
         lines.push("| Element | Figma Variable | Value |");
         lines.push("|---------|---------------|-------|");
         for (const vd of variantData) {
-            const nameMatch = vd.variantName.match(/Variant=([^,]+)/i);
-            const displayName = nameMatch ? nameMatch[1].trim() : vd.variantName;
+            // Same naming as the Variant Matrix: every property value, whatever the
+            // properties are called ("Variant=Secondary, Appearance=Critical" → "Secondary / Critical").
+            const displayName = cleanVariantName(vd.variantName);
             // Section header for this variant
             lines.push(`| **${displayName}** | | |`);
-            // Background fills
-            for (const fill of vd.fills) {
-                const varName = fill.variableName || (fill.variableId ? varNameMap.get(fill.variableId) : undefined);
-                lines.push(`| Background | ${varName ? `\`${varName}\`` : "—"} | ${fill.hex} |`);
-            }
+            const tokenCell = (c) => {
+                const varName = c.variableName || (c.variableId ? varNameMap.get(c.variableId) : undefined);
+                return varName ? `\`${varName}\`` : "—";
+            };
+            // Multi-path icons and repeated shapes would otherwise emit identical rows
+            const emitted = new Set();
+            const pushRow = (label, c) => {
+                const row = `| ${label} | ${tokenCell(c)} | ${c.hex} |`;
+                if (emitted.has(row))
+                    return;
+                emitted.add(row);
+                lines.push(row);
+            };
+            // Background — the variant's own surface only. Say so when there isn't one.
+            const bgLabel = vd.backgroundLayer ? `Background (${vd.backgroundLayer})` : "Background";
+            if (vd.fills.length === 0) {
+                lines.push("| Background | — | none (transparent) |");
+            }
+            for (const fill of vd.fills)
+                pushRow(bgLabel, fill);
+            // Fills on inner layers — reported under the layer's name, never as a background
+            for (const fill of vd.descendantFills)
+                pushRow(`Fill (${fill.nodeName})`, fill);
+            // Icon artwork colors
+            for (const c of vd.iconColors)
+                pushRow(c.iconLabel ? `Icon (${c.iconLabel})` : "Icon", c);
             // Text colors
             for (const text of vd.textColors) {
                 const varName = text.variableName || (text.variableId ? varNameMap.get(text.variableId) : undefined);
@@ -1775,10 +2076,39 @@ function generateVisualSpecsSection(node, enrichedData, variantData, varNameMap
     }
     // Spacing tokens with variable names
     const visualNode = resolveVisualNode(node);
-    const spacingTokens = collectSpacingTokens(visualNode, varNameMap);
-    if (spacingTokens.length > 0) {
+    const comparison = setNode?.type === "COMPONENT_SET" && setNode.children?.length > 1
+        ? collectSpacingAcrossVariants(setNode, varNameMap)
+        : null;
+    const spacingTokens = comparison ? [] : collectSpacingTokens(visualNode, varNameMap);
+    if (comparison && comparison.rows.length > 0) {
+        lines.push("### Spacing Tokens");
+        lines.push("");
+        lines.push(`_Compared across all ${comparison.variantCount} variants — a single value means every variant agrees._`);
+        lines.push("");
+        lines.push("| Property | Figma Variable | Value |");
+        lines.push("|----------|---------------|-------|");
+        for (const row of comparison.rows) {
+            lines.push(`| ${row.property} | ${row.variableCell} | ${row.valueCell} |`);
+        }
+        lines.push("");
+        if (comparison.inconsistencies.length > 0) {
+            lines.push("#### Spacing Inconsistencies");
+            lines.push("");
+            lines.push("_A property tokenized on most variants but hardcoded on a few usually means an accidental edit._");
+            lines.push("");
+            for (const note of comparison.inconsistencies)
+                lines.push(`- ${note}`);
+            lines.push("");
+        }
+    }
+    else if (spacingTokens.length > 0) {
         lines.push("### Spacing Tokens");
         lines.push("");
+        // A lone variant doesn't speak for its whole set — say which one this is
+        if (isVariantName(visualNode.name || "") || /^[^=,]+=[^=,]+$/.test(visualNode.name || "")) {
+            lines.push(`_Describes the \`${cleanVariantName(visualNode.name)}\` variant only._`);
+            lines.push("");
+        }
         lines.push("| Property | Figma Variable | Value |");
         lines.push("|----------|---------------|-------|");
         for (const token of spacingTokens) {
@@ -2686,8 +3016,14 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                     logger.warn("Could not load bridge variables for doc token names — colors may fall back to hex");
                 }
             }
-            // Collect per-variant color/icon data
-            const variantData = collectAllVariantData(node, varNameMap);
+            // Collect per-variant color/icon data. The REST response carries component
+            // metadata next to the document — that's what names the icon actually sitting
+            // in a slot, instead of guessing from its layer name.
+            const componentLookup = {
+                components: nodeData.components,
+                componentSets: nodeData.componentSets,
+            };
+            const variantData = collectAllVariantData(node, varNameMap, componentLookup);
             // Resolve clean component name (prefer set name over variant name)
             const componentName = resolveComponentName(node, setInfo.setName, codeInfo?.filePath?.split("/").pop()?.replace(/\.\w+$/, ""));
             // Prefer markdown description (has headers/bold markers for parsing) over plain text
@@ -2812,14 +3148,14 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                 }
             }
             if (s.statesAndVariants) {
-                const variantsSection = generateStatesAndVariantsSection(nodeForVariants, variantData);
+                const variantsSection = generateStatesAndVariantsSection(nodeForVariants, variantData, componentLookup);
                 if (variantsSection) {
                     parts.push(variantsSection);
                     includedSections.push("statesAndVariants");
                 }
             }
             if (s.visualSpecs) {
-                parts.push(generateVisualSpecsSection(nodeForVisual, enrichedData, variantData, varNameMap));
+                parts.push(generateVisualSpecsSection(nodeForVisual, enrichedData, variantData, varNameMap, node));
                 includedSections.push("visualSpecs");
             }
             if (s.typography) {

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

@@ -59,6 +59,24 @@ export class DesignSystemManifestCache {
         return stats;
     }
 }
+/**
+ * Decide whether a component search can be answered from this manifest.
+ *
+ * When the components fetch failed (`loadWarning` set) and the manifest holds
+ * no components at all, there is nothing to search — and an empty result list
+ * would read as "no such component exists". Returns the error message to
+ * surface in that case, or null when the search can proceed (including a
+ * genuinely empty file, which loads WITHOUT a warning).
+ */
+export function componentSearchLoadFailure(manifest, loadWarning) {
+    if (!loadWarning)
+        return null;
+    const loaded = Object.keys(manifest.components).length +
+        Object.keys(manifest.componentSets).length;
+    if (loaded > 0)
+        return null;
+    return `Component search could not run: ${loadWarning}`;
+}
 /**
  * Search components by name, category, or description
  */

package/dist/cloudflare/core/tokens/schemas.js

@@ -66,12 +66,12 @@ export const ExportTokensInputSchema = z.object({
     outputPath: z
         .string()
         .optional()
-        .describe("Filesystem path to write the output file(s) to. Relative paths resolve against the project root (the directory containing tokens.config.json) or cwd if no config. When omitted, the output is returned inline in the response (suitable for the AI to inspect or write via its own file tools)."),
+        .describe("Where to write the output. Treated as a DIRECTORY by default — each generated file (e.g. tokens.tokens.json, tokens.css) is written inside it and the directory is created if missing. Treated as a FILE when it is an existing file or ends in a token-file extension (.json, .css, .scss, .less, .ts, .js): the export must then produce exactly ONE file (one format, no splitByMode/splitByCollection — combine with collectionIds to re-export a single collection into e.g. typography.tokens.json), which is written at exactly that path, overwriting it. A file path combined with a multi-file export is rejected with an explanatory error before anything is written. End the path with '/' to force directory handling. Relative paths resolve against the project root (the directory containing tokens.config.json) or cwd if no config. When omitted, the output is returned inline in the response (suitable for the AI to inspect or write via its own file tools)."),
     configPath: z
         .string()
         .optional()
         .describe("Explicit path to a tokens.config.json file. When omitted, the tool walks up from cwd looking for one — typical case is zero-arg."),
-    strategy: SyncStrategySchema.optional().describe("How to handle existing output files. 'merge' (default) diffs against current contents and writes only changed tokens, preserving code-only additions. 'replace' wipes and rewrites. 'dry-run' computes the diff and reports what would change without writing."),
+    strategy: SyncStrategySchema.optional().describe("How to handle existing output files. Export always replaces a target file's contents with the current Figma state — it does not merge token-by-token. 'merge' (default) is the SAFE mode: it refuses to write, leaving the file untouched, if overwriting an existing DTCG file would delete tokens the export does not manage (hand-added tokens, or tokens from collections not included in this export). 'replace' overwrites unconditionally. 'dry-run' reports what would be written without writing."),
     prefix: z
         .string()
         .optional()