@mp3wizard/figma-console-mcp 1.32.3 → 1.34.1

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

@@ -0,0 +1,232 @@
+/**
+ * DTCG dialect helpers — legacy vs 2025.10 value encodings.
+ *
+ * The token pipeline historically speaks the "legacy" DTCG dialect: colors
+ * as hex strings ("#4085F2"), FLOAT dimensions as bare numbers. The DTCG
+ * 2025.10 spec (https://tr.designtokens.org/format/) switched to object
+ * forms:
+ *
+ *   color     = { colorSpace: "srgb", components: [r, g, b], alpha?, hex? }
+ *   dimension = { value: number, unit: "px" | "rem" }
+ *   duration  = { value: number, unit: "ms" | "s" }   (we already emit this)
+ *
+ * Export stays legacy by default (downstream consumers depend on it) and
+ * opts into 2025 via the `dtcgDialect` option. Import accepts BOTH dialects
+ * unconditionally. This module centralizes:
+ *
+ *   - 2025 encoding helpers used by the dtcg/json formatters at render time
+ *   - dialect-agnostic canonicalization used by the import diff so a 2025
+ *     color object compares equal to the same color's legacy hex string
+ *     (both are quantized to 1/255 per channel, tolerating the 8-bit
+ *     precision loss inherent to hex)
+ *   - stripping of the transient `rawColor` field the converter carries on
+ *     COLOR TokenValues (full-precision floats for 2025 components) so it
+ *     never leaks into serialized output
+ */
+export function clamp01(n) {
+    if (Number.isNaN(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+function byteHex(f) {
+    return Math.round(clamp01(f) * 255)
+        .toString(16)
+        .padStart(2, "0");
+}
+/**
+ * Canonicalize any color-like literal to a lowercase 8-digit hex string
+ * (`#rrggbbaa`), or return null when the literal isn't recognizably a color.
+ *
+ * Accepts:
+ *   - hex strings: #rgb, #rrggbb, #rrggbbaa
+ *   - 2025.10 color objects with srgb (or unspecified) colorSpace +
+ *     3 numeric components (+ optional alpha)
+ *   - color objects with a hex fallback field (any colorSpace) + optional alpha
+ *
+ * Both the components form and the hex form quantize to 1 / 255 per channel,
+ * so a full-precision components array compares equal to the hex string the
+ * legacy pipeline derived from the same Figma floats.
+ */
+export function colorLiteralToCanonicalHex(literal) {
+    if (typeof literal === "string") {
+        const m = literal
+            .trim()
+            .match(/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+        if (!m)
+            return null;
+        let digits = m[1].toLowerCase();
+        if (digits.length === 3) {
+            digits = digits
+                .split("")
+                .map((c) => c + c)
+                .join("");
+        }
+        if (digits.length === 6)
+            digits += "ff";
+        return `#${digits}`;
+    }
+    if (literal && typeof literal === "object" && !Array.isArray(literal)) {
+        const o = literal;
+        const colorSpace = typeof o.colorSpace === "string" ? o.colorSpace : undefined;
+        const comps = o.components;
+        if ((colorSpace === undefined || colorSpace === "srgb") &&
+            Array.isArray(comps) &&
+            comps.length === 3 &&
+            comps.every((c) => typeof c === "number")) {
+            const [r, g, b] = comps;
+            const a = typeof o.alpha === "number" ? o.alpha : 1;
+            return `#${byteHex(r)}${byteHex(g)}${byteHex(b)}${byteHex(a)}`;
+        }
+        if (typeof o.hex === "string") {
+            const base = colorLiteralToCanonicalHex(o.hex);
+            if (!base)
+                return null;
+            if (typeof o.alpha === "number") {
+                return base.slice(0, 7) + byteHex(o.alpha);
+            }
+            return base;
+        }
+    }
+    return null;
+}
+/**
+ * Parse a hex color string to raw rgba floats (0–1). Returns null on
+ * anything that isn't a valid 3/6/8-digit hex string.
+ */
+export function hexToRawRgba(hex) {
+    const canonical = colorLiteralToCanonicalHex(hex);
+    if (!canonical)
+        return null;
+    const d = canonical.slice(1);
+    return {
+        r: parseInt(d.slice(0, 2), 16) / 255,
+        g: parseInt(d.slice(2, 4), 16) / 255,
+        b: parseInt(d.slice(4, 6), 16) / 255,
+        a: parseInt(d.slice(6, 8), 16) / 255,
+    };
+}
+/**
+ * Encode a color TokenValue in the DTCG 2025.10 object form.
+ *
+ * Prefers the converter's transient `rawColor` floats (full precision — NOT
+ * round-tripped through 8-bit hex); falls back to parsing a hex-string
+ * literal. Literals already in object form pass through verbatim. Returns
+ * null when the value can't be encoded (caller keeps the legacy rendering).
+ *
+ * `alpha` is emitted only when < 1; `hex` is always included as the interop
+ * courtesy field (#RRGGBB, alpha carried separately).
+ */
+export function colorValueTo2025(value) {
+    const lit = value.literal;
+    if (lit && typeof lit === "object" && !Array.isArray(lit)) {
+        // Already object-form (e.g. a re-exported 2025 document) — pass through.
+        const o = lit;
+        if ("colorSpace" in o || "components" in o || "hex" in o)
+            return o;
+        return null;
+    }
+    let floats = value.rawColor ?? null;
+    if (!floats && typeof lit === "string") {
+        floats = hexToRawRgba(lit);
+    }
+    if (!floats)
+        return null;
+    const { r, g, b, a } = floats;
+    return {
+        colorSpace: "srgb",
+        components: [r, g, b],
+        ...(a < 1 ? { alpha: a } : {}),
+        hex: `#${byteHex(r)}${byteHex(g)}${byteHex(b)}`.toUpperCase(),
+    };
+}
+/**
+ * Encode a dimension literal in the DTCG 2025.10 object form. The converter
+ * emits Figma FLOAT dimensions as bare unitless numbers conventionally
+ * interpreted as px (the same convention the css/json formatters use), so
+ * only bare finite numbers are converted; everything else (unit strings,
+ * pre-encoded objects) keeps its current rendering.
+ */
+export function dimensionLiteralTo2025(literal) {
+    if (typeof literal === "number" && Number.isFinite(literal)) {
+        return { value: literal, unit: "px" };
+    }
+    return null;
+}
+/**
+ * Normalize a TokenValue to a dialect-agnostic comparable form for diffing:
+ *
+ *   - the transient `rawColor` field is dropped (Figma-side values carry it;
+ *     parsed code-side values never do)
+ *   - color-like literals (hex strings OR 2025 color objects) normalize to a
+ *     lowercase 8-digit hex string, quantized to 1/255 per channel
+ *   - `{ value, unit }` objects with px/ms normalize to the bare number
+ *     ("s" converts to ms first), so `{value: 16, unit: "px"}` equals 16 and
+ *     `{value: 0.3, unit: "s"}` equals `{value: 300, unit: "ms"}`
+ *   - "16px"-style strings normalize to the bare number
+ *
+ * Conservative by design: anything not confidently recognized is returned
+ * unchanged (minus rawColor), falling back to the existing deep comparison.
+ */
+export function canonicalizeTokenValueForComparison(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return v;
+    const obj = v;
+    if (!("literal" in obj) && !("reference" in obj))
+        return v;
+    const { rawColor: _rawColor, ...rest } = obj;
+    if (rest.literal !== undefined) {
+        const hex = colorLiteralToCanonicalHex(rest.literal);
+        if (hex !== null)
+            return { ...rest, literal: hex };
+        const num = numericLiteralToCanonical(rest.literal);
+        if (num !== null)
+            return { ...rest, literal: num };
+    }
+    return rest;
+}
+/**
+ * Normalize dimension/duration-shaped literals to a bare comparable number:
+ *   - `{ value: n, unit: "px" | "ms" }` → n
+ *   - `{ value: n, unit: "s" }` → n * 1000 (canonical ms)
+ *   - `"16px"` strings → 16
+ * Returns null for everything else (including rem/em/% and objects with
+ * extra fields — those keep structural comparison).
+ */
+function numericLiteralToCanonical(literal) {
+    if (typeof literal === "string") {
+        const m = literal.trim().match(/^(-?(?:\d+\.?\d*|\.\d+))px$/i);
+        return m ? Number(m[1]) : null;
+    }
+    if (literal &&
+        typeof literal === "object" &&
+        !Array.isArray(literal) &&
+        Object.keys(literal).length === 2) {
+        const o = literal;
+        if (typeof o.value === "number" && typeof o.unit === "string") {
+            if (o.unit === "px" || o.unit === "ms")
+                return o.value;
+            if (o.unit === "s")
+                return o.value * 1000;
+        }
+    }
+    return null;
+}
+/**
+ * Return a copy of a mode-keyed TokenValue map with the transient `rawColor`
+ * field removed from every entry. Used wherever values get serialized
+ * (lastSyncedValue snapshots, diff-plan samples) so the transient field never
+ * appears in output — keeping legacy output byte-identical.
+ */
+export function stripRawColorFromValues(values) {
+    const out = {};
+    for (const [k, v] of Object.entries(values)) {
+        if (v && typeof v === "object" && "rawColor" in v) {
+            const { rawColor: _rawColor, ...rest } = v;
+            out[k] = rest;
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}

package/dist/cloudflare/core/tokens/figma-converter.js

@@ -11,6 +11,8 @@
  * normalized to our TokenValue shape, and Figma IDs preserved in
  * $extensions["figma-console-mcp"] for round-trip non-destructiveness.
  */
+import { slugifySetName } from "./alias-resolver.js";
+import { stripRawColorFromValues } from "./dialect.js";
 /**
  * Convert a Figma variables payload to our canonical TokenDocument.
  */
@@ -20,11 +22,19 @@ export function convertFigmaVariablesToDocument(payload, opts = {}) {
     const variableById = new Map();
     for (const v of payload.variables)
         variableById.set(v.id, v);
+    // Collection name lookup — alias references must carry the owning set so
+    // same-path tokens across collections don't misresolve (and so emitted
+    // DTCG references point at the actual set group in the output tree).
+    // Built over ALL collections (not just the filtered ones) because an
+    // alias can target a variable in a collection outside the export scope.
+    const collectionNameById = new Map();
+    for (const c of payload.collections)
+        collectionNameById.set(c.id, c.name);
     // Filter collections per scope.
     const wantedCollections = opts.collectionIds?.length
         ? payload.collections.filter((c) => opts.collectionIds.includes(c.id))
         : payload.collections;
-    const sets = wantedCollections.map((collection) => convertCollection(collection, payload.variables, variableById, opts, warnings));
+    const sets = wantedCollections.map((collection) => convertCollection(collection, payload.variables, variableById, collectionNameById, opts, warnings));
     return {
         document: {
             $schema: "https://figma-console-mcp.southleft.com/schemas/dtcg-extended-v1.json",
@@ -38,7 +48,7 @@ export function convertFigmaVariablesToDocument(payload, opts = {}) {
         warnings,
     };
 }
-function convertCollection(collection, allVariables, variableById, opts, warnings) {
+function convertCollection(collection, allVariables, variableById, collectionNameById, opts, warnings) {
     // Mode filter: keep only modes the caller wants, intersected with what
     // the collection actually has.
     const wantedModes = !opts.modes || opts.modes === "all"
@@ -46,7 +56,7 @@ function convertCollection(collection, allVariables, variableById, opts, warning
         : collection.modes.filter((m) => opts.modes.includes(m.name));
     // Variables in this collection.
     const collectionVars = allVariables.filter((v) => v.variableCollectionId === collection.id);
-    const tokens = collectionVars.map((variable) => convertVariable(variable, wantedModes, variableById, opts, warnings));
+    const tokens = collectionVars.map((variable) => convertVariable(variable, wantedModes, variableById, collectionNameById, opts, warnings));
     return {
         name: collection.name,
         modes: wantedModes.map((m) => m.name),
@@ -56,26 +66,47 @@ function convertCollection(collection, allVariables, variableById, opts, warning
         },
     };
 }
-function convertVariable(variable, wantedModes, variableById, opts, warnings) {
-    // Derive the hierarchical path from the Figma variable name. Figma uses
-    // slashes to indicate grouping: "color/brand/primary" → ["color", "brand", "primary"].
+/**
+ * Derive a variable's token path from its Figma name. Strips the configured
+ * prefix, splits on "/", and for TIMING/EASING variables drops the trailing
+ * type segment Figma appends to Config-2026 motion variables (e.g.
+ * "motion/duration/quick/Timing" → ["motion", "duration", "quick"]).
+ */
+function variableTokenPath(variable, opts) {
     let name = variable.name;
     if (opts.stripPrefix && name.startsWith(opts.stripPrefix)) {
         name = name.slice(opts.stripPrefix.length);
     }
-    const path = name.split("/").filter(Boolean);
+    const segments = name.split("/").filter(Boolean);
+    let strippedTypeSuffix = false;
+    if ((variable.resolvedType === "TIMING" || variable.resolvedType === "EASING") &&
+        segments.length > 1 &&
+        /^(timing|easing)$/i.test(segments[segments.length - 1])) {
+        segments.pop();
+        strippedTypeSuffix = true;
+    }
+    return { path: segments, strippedTypeSuffix };
+}
+function convertVariable(variable, wantedModes, variableById, collectionNameById, opts, warnings) {
+    // Derive the hierarchical path from the Figma variable name. Figma uses
+    // slashes to indicate grouping: "color/brand/primary" → ["color", "brand", "primary"].
+    const { path, strippedTypeSuffix } = variableTokenPath(variable, opts);
     // Map resolvedType to TokenType.
     const type = mapResolvedType(variable.resolvedType, variable.name, warnings);
     // Convert each (mode → value) pair to our TokenValue shape, filtered by
-    // the wanted modes.
+    // the wanted modes. Spring easings can't be expressed in DTCG — their
+    // parameters get stashed per-mode in the token's extensions.
     const values = {};
+    const springByMode = {};
     for (const mode of wantedModes) {
         const rawValue = variable.valuesByMode[mode.modeId];
         if (rawValue === undefined) {
             warnings.push(`Variable "${variable.name}" has no value for mode "${mode.name}" (${mode.modeId}); skipping that mode.`);
             continue;
         }
-        values[mode.name] = convertValue(rawValue, variable.resolvedType, variableById, warnings);
+        values[mode.name] = convertValue(rawValue, variable, mode.name, variableById, collectionNameById, opts, warnings, (spring) => {
+            springByMode[mode.name] = spring;
+        });
     }
     return {
         path,
@@ -86,14 +117,45 @@ function convertVariable(variable, wantedModes, variableById, opts, warnings) {
             "figma-console-mcp": {
                 variableId: variable.id,
                 collectionId: variable.variableCollectionId,
+                // The Figma-native type is what import needs to decide writability
+                // — TIMING/EASING variables cannot be written via the Plugin API,
+                // and FLOAT variables whose token type is "duration" (name-inferred)
+                // must NOT be mistaken for TIMING.
+                figmaResolvedType: variable.resolvedType,
+                // Preserve the original variable name when the token path dropped
+                // the trailing "Timing"/"Easing" segment, so round-trip can
+                // reconstruct it.
+                ...(strippedTypeSuffix ? { figmaName: variable.name } : {}),
+                ...(Object.keys(springByMode).length > 0 ? { spring: springByMode } : {}),
+                // Scopes: stash only when NON-default. ["ALL_SCOPES"] (Figma's
+                // default) and empty/absent arrays are omitted so pre-existing
+                // exports stay byte-identical. codeSyntax: stash only when
+                // non-empty, same reasoning.
+                ...(hasNonDefaultScopes(variable.scopes)
+                    ? { scopes: [...variable.scopes] }
+                    : {}),
+                ...(variable.codeSyntax && Object.keys(variable.codeSyntax).length > 0
+                    ? { codeSyntax: { ...variable.codeSyntax } }
+                    : {}),
                 lastSyncedAt: new Date().toISOString(),
                 // We snapshot the synced value so future merge calls can detect
-                // two-sided conflicts.
-                lastSyncedValue: { ...values },
+                // two-sided conflicts. rawColor is transient render-time data and
+                // must not leak into serialized extensions (legacy output stays
+                // byte-identical).
+                lastSyncedValue: stripRawColorFromValues({ ...values }),
             },
         },
     };
 }
+/**
+ * True when a variable's scopes array is meaningfully restrictive — i.e.
+ * present, non-empty, and not just the default ["ALL_SCOPES"].
+ */
+function hasNonDefaultScopes(scopes) {
+    if (!Array.isArray(scopes) || scopes.length === 0)
+        return false;
+    return !(scopes.length === 1 && scopes[0] === "ALL_SCOPES");
+}
 function mapResolvedType(resolvedType, variableName, warnings) {
     switch (resolvedType) {
         case "COLOR":
@@ -109,6 +171,12 @@ function mapResolvedType(resolvedType, variableName, warnings) {
             return inferStringType(variableName);
         case "BOOLEAN":
             return "boolean";
+        case "TIMING":
+            // Config-2026 motion duration variables — plain numbers in SECONDS.
+            return "duration";
+        case "EASING":
+            // Config-2026 easing variables — bezier (or spring) curve objects.
+            return "cubicBezier";
         default: {
             const _exhaustive = resolvedType;
             warnings.push(`Unknown resolvedType "${_exhaustive}" for variable "${variableName}"; treating as string.`);
@@ -133,7 +201,8 @@ function inferStringType(variableName) {
         return "fontFamily";
     return "string";
 }
-function convertValue(rawValue, resolvedType, variableById, warnings) {
+function convertValue(rawValue, variable, modeName, variableById, collectionNameById, opts, warnings, onSpring) {
+    const resolvedType = variable.resolvedType;
     // Alias references: convert variable ID → path-based reference for DTCG.
     if (isVariableAlias(rawValue)) {
         const target = variableById.get(rawValue.id);
@@ -146,14 +215,38 @@ function convertValue(rawValue, resolvedType, variableById, warnings) {
             warnings.push(`Alias to unknown variable ID ${rawValue.id} (likely a cross-library reference). Original ID preserved in reference for round-trip.`);
             return { reference: `{__library:${rawValue.id}}` };
         }
-        // The DTCG alias path uses dots: "color.brand.primary".
-        const dotPath = target.name.replace(/\//g, ".");
-        return { reference: `{${dotPath}}` };
+        // The DTCG alias path uses dots, QUALIFIED by the target's set group
+        // (`{<set-slug>.color.brand.primary}`). The set qualifier does two
+        // jobs: (1) same-path tokens in different collections resolve to the
+        // right target instead of "whichever set was indexed last", and
+        // (2) the emitted DTCG reference points at the actual location in the
+        // output tree (tokens nest under the slugified set group), so
+        // external DTCG tools like Style Dictionary v4 can resolve it.
+        const targetPath = variableTokenPath(target, opts).path;
+        const dotPath = targetPath.join(".");
+        const targetCollectionName = collectionNameById.get(target.variableCollectionId);
+        if (!targetCollectionName) {
+            warnings.push(`Alias target "${target.name}" belongs to unknown collection ${target.variableCollectionId} — emitting an unqualified reference.`);
+            return { reference: `{${dotPath}}` };
+        }
+        return { reference: `{${slugifySetName(targetCollectionName)}.${dotPath}}` };
     }
     // Literal values per type.
     if (resolvedType === "COLOR") {
         if (typeof rawValue === "object" && rawValue !== null && "r" in rawValue) {
-            return { literal: rgbaToHex(rawValue) };
+            // The hex string stays the literal (legacy dialect + back-compat), but
+            // we also carry the raw full-precision floats so the 2025.10 dialect
+            // can emit `components` without round-tripping through 8-bit hex.
+            // `rawColor` is transient — see TokenValue.rawColor in types.ts.
+            return {
+                literal: rgbaToHex(rawValue),
+                rawColor: {
+                    r: rawValue.r,
+                    g: rawValue.g,
+                    b: rawValue.b,
+                    a: rawValue.a ?? 1,
+                },
+            };
         }
         warnings.push(`COLOR value isn't an RGB object: ${JSON.stringify(rawValue)}`);
         return { literal: String(rawValue) };
@@ -164,6 +257,41 @@ function convertValue(rawValue, resolvedType, variableById, warnings) {
     if (resolvedType === "BOOLEAN") {
         return { literal: Boolean(rawValue) };
     }
+    if (resolvedType === "TIMING") {
+        // Figma TIMING values are plain numbers in SECONDS. DTCG duration uses
+        // the structured `{ value, unit }` form — emit milliseconds.
+        if (typeof rawValue === "number") {
+            return { literal: { value: rawValue * 1000, unit: "ms" } };
+        }
+        warnings.push(`TIMING value for "${variable.name}" (mode "${modeName}") isn't a number: ${JSON.stringify(rawValue)} — emitting as string.`);
+        return { literal: String(rawValue) };
+    }
+    if (resolvedType === "EASING") {
+        const easing = rawValue;
+        const b = easing?.bezierValues;
+        if (b &&
+            typeof b.p1x === "number" &&
+            typeof b.p1y === "number" &&
+            typeof b.p2x === "number" &&
+            typeof b.p2y === "number") {
+            // DTCG cubicBezier: [p1x, p1y, p2x, p2y].
+            return { literal: [b.p1x, b.p1y, b.p2x, b.p2y] };
+        }
+        if (easing && typeof easing === "object" && easing.springValues) {
+            // Spring easings have no bezier representation — DTCG cannot express
+            // springs. Emit a standard "ease" bezier as a usable approximation
+            // and preserve the spring parameters in the token's
+            // figma-console-mcp extensions for round-trip.
+            warnings.push(`EASING variable "${variable.name}" (mode "${modeName}") is a spring (${easing.easingType ?? "unknown type"}) — DTCG cannot represent springs. Emitted a fallback cubicBezier; spring parameters preserved in $extensions["figma-console-mcp"].spring.`);
+            onSpring({
+                easingType: easing.easingType,
+                springValues: easing.springValues,
+            });
+            return { literal: [0.25, 0.1, 0.25, 1.0] };
+        }
+        warnings.push(`EASING value for "${variable.name}" (mode "${modeName}") has no usable bezierValues or springValues: ${JSON.stringify(rawValue)} — emitting as string.`);
+        return { literal: String(rawValue) };
+    }
     // STRING and fallthrough.
     return { literal: typeof rawValue === "string" ? rawValue : String(rawValue) };
 }

package/dist/cloudflare/core/tokens/formatters/css-vars.js

@@ -18,9 +18,14 @@
  *   - splitByMode emits one file per mode with just that mode's values.
  *   - splitByCollection emits one file per set.
  */
+import { buildTokenIndex, referenceTargetPath } from "../alias-resolver.js";
 export function formatCssVars(doc, opts) {
     const warnings = [];
     const files = [];
+    // Index over the WHOLE document (not per-file subsets) so set-qualified
+    // alias references ({set-slug.path}) resolve to their target token's own
+    // path when generating var(--...) names.
+    const tokenIndex = buildTokenIndex(doc, warnings);
     const splitByMode = opts.target.splitByMode ?? false;
     const splitByCollection = opts.target.splitByCollection ?? false;
     const prefix = opts.target.prefix ?? "";
@@ -30,7 +35,7 @@ export function formatCssVars(doc, opts) {
             for (const mode of set.modes) {
                 files.push({
                     path: filenameFor(opts, set, mode),
-                    content: renderSingleSelector(doc.sets.filter((s) => s.name === set.name), mode, selectorFor(mode), prefix, warnings),
+                    content: renderSingleSelector(doc.sets.filter((s) => s.name === set.name), mode, selectorFor(mode), prefix, tokenIndex, warnings),
                 });
             }
         }
@@ -45,7 +50,7 @@ export function formatCssVars(doc, opts) {
             const setsWithMode = doc.sets.filter((s) => s.modes.includes(mode));
             files.push({
                 path: filenameFor(opts, undefined, mode),
-                content: renderSingleSelector(setsWithMode, mode, selectorFor(mode), prefix, warnings),
+                content: renderSingleSelector(setsWithMode, mode, selectorFor(mode), prefix, tokenIndex, warnings),
             });
         }
     }
@@ -54,7 +59,7 @@ export function formatCssVars(doc, opts) {
         for (const set of doc.sets) {
             files.push({
                 path: filenameFor(opts, set),
-                content: renderMultiSelector([set], prefix, warnings),
+                content: renderMultiSelector([set], prefix, tokenIndex, warnings),
             });
         }
     }
@@ -62,7 +67,7 @@ export function formatCssVars(doc, opts) {
         // Single file with everything.
         files.push({
             path: filenameFor(opts),
-            content: renderMultiSelector(doc.sets, prefix, warnings),
+            content: renderMultiSelector(doc.sets, prefix, tokenIndex, warnings),
         });
     }
     return { files, warnings };
@@ -107,7 +112,7 @@ function selectorFor(mode) {
  * Render all tokens across the given sets under a single selector. Used when
  * one file holds one mode's worth of vars (splitByMode output).
  */
-function renderSingleSelector(sets, mode, selector, prefix, warnings) {
+function renderSingleSelector(sets, mode, selector, prefix, tokenIndex, warnings) {
     const lines = [];
     lines.push(`/* Generated by figma-console-mcp — do not edit by hand */`);
     lines.push(`${selector} {`);
@@ -116,7 +121,7 @@ function renderSingleSelector(sets, mode, selector, prefix, warnings) {
             const value = token.values[mode];
             if (!value)
                 continue;
-            emitTokenLines(token, value, prefix, lines, warnings);
+            emitTokenLines(token, value, prefix, tokenIndex, lines, warnings);
         }
     }
     lines.push(`}`);
@@ -127,7 +132,7 @@ function renderSingleSelector(sets, mode, selector, prefix, warnings) {
  * Render multiple sets across multiple modes in one file. Each mode gets its
  * own selector block.
  */
-function renderMultiSelector(sets, prefix, warnings) {
+function renderMultiSelector(sets, prefix, tokenIndex, warnings) {
     const lines = [];
     lines.push(`/* Generated by figma-console-mcp — do not edit by hand */`);
     // Collect all (mode, selector) pairs across all sets.
@@ -148,7 +153,7 @@ function renderMultiSelector(sets, prefix, warnings) {
                 const value = token.values[mode];
                 if (!value)
                     continue;
-                emitTokenLines(token, value, prefix, lines, warnings);
+                emitTokenLines(token, value, prefix, tokenIndex, lines, warnings);
             }
         }
         lines.push(`}`);
@@ -161,7 +166,7 @@ function renderMultiSelector(sets, prefix, warnings) {
  * Primitives emit one line; composite tokens (typography, shadow) expand
  * into multiple lines.
  */
-function emitTokenLines(token, value, prefix, out, warnings) {
+function emitTokenLines(token, value, prefix, tokenIndex, out, warnings) {
     // Every path segment must be a valid CSS identifier — slugify each to
     // normalize spaces, dots, and other special characters that show up in
     // real Figma variable names (e.g. "tailwind colors/purple/50").
@@ -180,9 +185,13 @@ function emitTokenLines(token, value, prefix, out, warnings) {
             out.push(`  /* ${cssName}: skipped — cross-library alias to ${originalId} */`);
             return;
         }
-        // Alias → var(--other) so CSS cascading semantics are preserved. The
-        // target path goes through the same slugify treatment as the source.
-        const refPath = bareRef.split(".");
+        // Alias → var(--other) so CSS cascading semantics are preserved.
+        // Resolve set-qualified references ({set-slug.path}) to the target
+        // token's own path via the index (the target's declaration is named
+        // from its path, without the set qualifier); bare/unresolvable refs
+        // fall back to the raw reference path. Either way the segments go
+        // through the same slugify treatment as the source.
+        const refPath = referenceTargetPath(value.reference, tokenIndex);
         const targetCssName = pathToCssName(refPath);
         out.push(`  ${cssName}: var(--${prefix}${targetCssName});`);
         return;