@mp3wizard/figma-console-mcp 1.32.3 → 1.34.1

package/dist/cloudflare/core/tokens/formatters/dtcg.js

@@ -19,11 +19,12 @@
  *      structured $value form. Aliases emit `"$value": "{path.to.target}"`.
  *
  * This formatter is the canonical output — the format every other
- * formatter (CSS variables today, Tailwind/SCSS/etc. in future minor
- * versions) ultimately derives from.
+ * formatter (CSS variables, Tailwind v4/v3, SCSS, TS module, JSON
+ * flat/nested, Style Dictionary v3, Tokens Studio) ultimately derives from.
  */
 import { FIGMA_MCP_EXTENSION_KEY } from "../types.js";
 import { formatDtcgReference } from "../alias-resolver.js";
+import { colorValueTo2025, dimensionLiteralTo2025, } from "../dialect.js";
 export function formatDtcg(doc, opts) {
     const warnings = [];
     const files = [];
@@ -35,6 +36,9 @@ export function formatDtcg(doc, opts) {
     //   4. neither → one file with everything
     const splitByMode = opts.target.splitByMode ?? false;
     const splitByCollection = opts.target.splitByCollection ?? false;
+    // Value-encoding dialect. 'legacy' (default) is byte-identical to the
+    // historical output; '2025' opts into DTCG 2025.10 object colors/dimensions.
+    const dialect = opts.target.dtcgDialect ?? "legacy";
     if (splitByMode && splitByCollection) {
         for (const set of doc.sets) {
             for (const mode of set.modes) {
@@ -43,7 +47,7 @@ export function formatDtcg(doc, opts) {
                     .filter((t) => t !== null);
                 files.push({
                     path: filenameFor(opts, set, mode),
-                    content: serializeAsDtcg({ sets: [{ ...set, modes: [mode], tokens: fileTokens }], meta: doc.meta }, warnings, mode),
+                    content: serializeAsDtcg({ sets: [{ ...set, modes: [mode], tokens: fileTokens }], meta: doc.meta }, warnings, dialect, mode),
                 });
             }
         }
@@ -65,7 +69,7 @@ export function formatDtcg(doc, opts) {
             }));
             files.push({
                 path: filenameFor(opts, undefined, mode),
-                content: serializeAsDtcg({ sets: fileSets, meta: doc.meta }, warnings, mode),
+                content: serializeAsDtcg({ sets: fileSets, meta: doc.meta }, warnings, dialect, mode),
             });
         }
     }
@@ -73,14 +77,14 @@ export function formatDtcg(doc, opts) {
         for (const set of doc.sets) {
             files.push({
                 path: filenameFor(opts, set),
-                content: serializeAsDtcg({ sets: [set], meta: doc.meta }, warnings),
+                content: serializeAsDtcg({ sets: [set], meta: doc.meta }, warnings, dialect),
             });
         }
     }
     else {
         files.push({
             path: filenameFor(opts),
-            content: serializeAsDtcg(doc, warnings),
+            content: serializeAsDtcg(doc, warnings, dialect),
         });
     }
     return { files, warnings };
@@ -131,7 +135,7 @@ function slugify(s) {
  * file represents — otherwise the parser sees only `$value` literals and
  * labels them "Default", which breaks round-trip diffs on multi-mode files.
  */
-function serializeAsDtcg(doc, warnings, fileMode) {
+function serializeAsDtcg(doc, warnings, dialect, fileMode) {
     // Build the nested DTCG group tree by walking every token's path and
     // building groups along the way.
     const tree = {};
@@ -176,7 +180,7 @@ function serializeAsDtcg(doc, warnings, fileMode) {
             tree[setKey] = setGroup;
         }
         for (const token of set.tokens) {
-            writeTokenIntoTree(setGroup, token, set.modes, warnings);
+            writeTokenIntoTree(setGroup, token, set.modes, warnings, dialect, fileMode);
         }
     }
     return JSON.stringify(sortKeys(tree), null, 2) + "\n";
@@ -193,20 +197,58 @@ function setKeyFor(set) {
 /**
  * Insert a token into the DTCG group tree at the right nested path.
  * Creates intermediate groups as needed.
+ *
+ * Leaf/group name conflicts (a variable named "color" alongside
+ * "color/primary") are kept — the leaf is emitted under the reserved "@"
+ * key inside the group, flagged with `leafRemap: true` in its
+ * figma-console-mcp $extensions so the parser can restore the original
+ * name on round-trip. A warning names both sides of the conflict.
  */
-function writeTokenIntoTree(root, token, setModes, warnings) {
+function writeTokenIntoTree(root, token, setModes, warnings, dialect, fileMode) {
     let cursor = root;
     for (let i = 0; i < token.path.length - 1; i++) {
         const segment = token.path[i];
         let next = cursor[segment];
-        if (!next || isToken(next)) {
+        if (next && isToken(next)) {
+            // A leaf token already occupies this segment and we need a group
+            // here. Keep both: demote the existing leaf to the reserved "@" key
+            // inside the new group.
+            const conflictPath = token.path.slice(0, i + 1).join("/");
+            warnings.push(`Name conflict: "${conflictPath}" is both a token and a group (needed by "${token.path.join("/")}"). Kept both — the leaf token "${conflictPath}" was emitted under "${conflictPath}/@" and round-trips back to its original name.`);
+            const group = { "@": markLeafRemap(next) };
+            cursor[segment] = group;
+            next = group;
+        }
+        else if (!next) {
             next = {};
             cursor[segment] = next;
         }
         cursor = next;
     }
     const leafKey = token.path[token.path.length - 1];
-    cursor[leafKey] = renderToken(token, setModes, warnings);
+    const rendered = renderToken(token, setModes, warnings, dialect, fileMode);
+    const existing = cursor[leafKey];
+    if (existing &&
+        typeof existing === "object" &&
+        !isToken(existing)) {
+        // A group already exists at this name (some other token nests under
+        // it). Keep both: emit this leaf under the reserved "@" key.
+        const conflictPath = token.path.join("/");
+        warnings.push(`Name conflict: token "${conflictPath}" collides with the group "${conflictPath}" (created by tokens nested under it). Kept both — the leaf was emitted under "${conflictPath}/@" and round-trips back to its original name.`);
+        existing["@"] = markLeafRemap(rendered);
+        return;
+    }
+    cursor[leafKey] = rendered;
+}
+/**
+ * Flag a rendered leaf token as remapped under the reserved "@" key so the
+ * parser can strip that synthetic path segment on round-trip.
+ */
+function markLeafRemap(tok) {
+    const existing = tok.$extensions?.[FIGMA_MCP_EXTENSION_KEY] ?? {};
+    tok.$extensions ??= {};
+    tok.$extensions[FIGMA_MCP_EXTENSION_KEY] = { ...existing, leafRemap: true };
+    return tok;
 }
 function isToken(node) {
     return "$value" in node;
@@ -215,11 +257,15 @@ function isToken(node) {
  * Convert an internal Token to its DTCG-encoded leaf form.
  *
  * Single-mode token: emits `{ $value, $type, ... }`.
- * Multi-mode token: emits one extension stash with all mode values, because
- * vanilla DTCG doesn't have a native multi-mode encoding. Callers who want
- * one-file-per-mode should set splitByMode at the formatter level.
+ * Multi-mode token: emits the primary mode as `$value` and stashes BOTH the
+ * primary mode's name (`primaryMode`) and the remaining mode values
+ * (`modes`) under `$extensions["figma-console-mcp"]`, because vanilla DTCG
+ * doesn't have a native multi-mode encoding. The parser reads the same keys
+ * back, so a Light/Dark collection round-trips losslessly even without
+ * splitByMode. Callers who want one-file-per-mode should set splitByMode at
+ * the formatter level.
  */
-function renderToken(token, setModes, warnings) {
+function renderToken(token, setModes, warnings, dialect, fileMode) {
     const result = {
         $value: "",
         $type: token.type,
@@ -228,23 +274,16 @@ function renderToken(token, setModes, warnings) {
         result.$description = token.description;
     const modeKeys = Object.keys(token.values);
     const isSingleMode = modeKeys.length === 1;
-    if (isSingleMode) {
-        const onlyValue = token.values[modeKeys[0]];
-        result.$value = encodeValue(onlyValue, token, warnings);
-    }
-    else {
-        // Multi-mode in a single file: pick the first mode as the canonical
-        // $value, stash the rest in $extensions for round-trip.
-        const primaryMode = setModes[0] in token.values ? setModes[0] : modeKeys[0];
-        result.$value = encodeValue(token.values[primaryMode], token, warnings);
-        const otherModes = {};
+    // Pick the primary mode: the set's first mode when the token has a value
+    // for it, otherwise the token's first mode.
+    const primaryMode = setModes[0] in token.values ? setModes[0] : modeKeys[0];
+    result.$value = encodeValue(token.values[primaryMode], token, warnings, dialect);
+    const otherModes = {};
+    if (!isSingleMode) {
         for (const m of modeKeys) {
             if (m === primaryMode)
                 continue;
-            otherModes[m] = encodeValue(token.values[m], token, warnings);
-        }
-        if (Object.keys(otherModes).length > 0) {
-            mergeExtension(result, "modes", otherModes);
+            otherModes[m] = encodeValue(token.values[m], token, warnings, dialect);
         }
     }
     // Preserve any pre-existing extensions (e.g. studio.tokens, our own metadata).
@@ -258,9 +297,29 @@ function renderToken(token, setModes, warnings) {
             }
         }
     }
+    // Mode round-trip metadata goes under OUR extension key (merged on top of
+    // any preserved figma-console-mcp payload so variableId etc. survive):
+    //   - `primaryMode` whenever the parser couldn't otherwise recover the
+    //     primary mode's name (i.e. it isn't covered by the file-level
+    //     fileMode stamp and isn't the "Default" fallback).
+    //   - `modes` with every non-primary mode's value for multi-mode tokens.
+    const needsPrimaryStash = primaryMode !== (fileMode ?? "Default");
+    const hasOtherModes = Object.keys(otherModes).length > 0;
+    if (needsPrimaryStash || hasOtherModes) {
+        const existing = result.$extensions?.[FIGMA_MCP_EXTENSION_KEY] ?? {};
+        mergeExtension(result, FIGMA_MCP_EXTENSION_KEY, {
+            ...existing,
+            primaryMode,
+            ...(hasOtherModes ? { modes: otherModes } : {}),
+        });
+    }
     return result;
 }
-function encodeValue(value, token, warnings) {
+function encodeValue(value, token, warnings, dialect) {
+    if (!value) {
+        warnings.push(`Token ${token.path.join(".")} has no mode values — emitting empty string.`);
+        return "";
+    }
     if (value.reference) {
         return formatDtcgReference(value.reference.replace(/^\{|\}$/g, "").split("."));
     }
@@ -268,6 +327,23 @@ function encodeValue(value, token, warnings) {
         warnings.push(`Token ${token.path.join(".")} has neither literal nor reference — emitting empty string.`);
         return "";
     }
+    // DTCG 2025.10 dialect: colors emit the object form (components from the
+    // converter's full-precision rawColor floats, hex kept as the interop
+    // courtesy field); dimension-typed bare numbers emit { value, unit: "px" }.
+    // duration already emits { value, unit: "ms" } in both dialects. Anything
+    // the encoders don't recognize keeps the legacy rendering.
+    if (dialect === "2025") {
+        if (token.type === "color") {
+            const encoded = colorValueTo2025(value);
+            if (encoded)
+                return encoded;
+        }
+        else if (token.type === "dimension") {
+            const encoded = dimensionLiteralTo2025(value.literal);
+            if (encoded)
+                return encoded;
+        }
+    }
     return value.literal;
 }
 function mergeExtension(token, key, payload) {

package/dist/cloudflare/core/tokens/formatters/json.js

@@ -31,11 +31,13 @@
  * aliases get a `null` (caller can decide how to fill those in).
  */
 import { buildTokenIndex, resolveAliasChain } from "../alias-resolver.js";
+import { colorValueTo2025, dimensionLiteralTo2025, } from "../dialect.js";
 export function formatJsonFlat(doc, opts) {
     const warnings = [];
     const files = [];
     const splitByCollection = opts.target.splitByCollection ?? false;
     const prefix = opts.target.prefix ?? "";
+    const dialect = opts.target.dtcgDialect ?? "legacy";
     // Plain JSON has no native alias mechanism — resolve aliases to their
     // literal target so consumers get usable values, not opaque `{ref}` strings.
     const tokenIndex = buildTokenIndex(doc);
@@ -43,14 +45,14 @@ export function formatJsonFlat(doc, opts) {
         for (const set of doc.sets) {
             files.push({
                 path: filenameFor(opts, set, "flat"),
-                content: renderFlat([set], prefix, tokenIndex, warnings),
+                content: renderFlat([set], prefix, tokenIndex, warnings, dialect),
             });
         }
     }
     else {
         files.push({
             path: filenameFor(opts, undefined, "flat"),
-            content: renderFlat(doc.sets, prefix, tokenIndex, warnings),
+            content: renderFlat(doc.sets, prefix, tokenIndex, warnings, dialect),
         });
     }
     return { files, warnings };
@@ -59,19 +61,20 @@ export function formatJsonNested(doc, opts) {
     const warnings = [];
     const files = [];
     const splitByCollection = opts.target.splitByCollection ?? false;
+    const dialect = opts.target.dtcgDialect ?? "legacy";
     const tokenIndex = buildTokenIndex(doc);
     if (splitByCollection) {
         for (const set of doc.sets) {
             files.push({
                 path: filenameFor(opts, set, "nested"),
-                content: renderNested([set], tokenIndex, warnings),
+                content: renderNested([set], tokenIndex, warnings, dialect),
             });
         }
     }
     else {
         files.push({
             path: filenameFor(opts, undefined, "nested"),
-            content: renderNested(doc.sets, tokenIndex, warnings),
+            content: renderNested(doc.sets, tokenIndex, warnings, dialect),
         });
     }
     return { files, warnings };
@@ -92,7 +95,7 @@ function slugify(s) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
 }
-function renderFlat(sets, prefix, tokenIndex, warnings) {
+function renderFlat(sets, prefix, tokenIndex, warnings, dialect) {
     const out = {};
     for (const set of sets) {
         const primaryMode = pickPrimaryMode(set.modes);
@@ -102,7 +105,7 @@ function renderFlat(sets, prefix, tokenIndex, warnings) {
                 const key = modeName === primaryMode
                     ? baseName
                     : `${baseName}--${slugify(modeName)}`;
-                const resolved = resolveValue(value, token, modeName, tokenIndex, warnings);
+                const resolved = resolveValue(value, token, modeName, tokenIndex, warnings, dialect);
                 if (resolved !== undefined)
                     out[key] = resolved;
             }
@@ -112,7 +115,7 @@ function renderFlat(sets, prefix, tokenIndex, warnings) {
     const sorted = Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b)));
     return JSON.stringify(sorted, null, 2) + "\n";
 }
-function renderNested(sets, tokenIndex, warnings) {
+function renderNested(sets, tokenIndex, warnings, dialect) {
     const out = {};
     for (const set of sets) {
         const isMultiMode = set.modes.length > 1;
@@ -131,7 +134,7 @@ function renderNested(sets, tokenIndex, warnings) {
             if (isMultiMode) {
                 const modeValues = {};
                 for (const [modeName, value] of Object.entries(token.values)) {
-                    const resolved = resolveValue(value, token, modeName, tokenIndex, warnings);
+                    const resolved = resolveValue(value, token, modeName, tokenIndex, warnings, dialect);
                     if (resolved !== undefined)
                         modeValues[modeName] = resolved;
                 }
@@ -140,7 +143,7 @@ function renderNested(sets, tokenIndex, warnings) {
             else {
                 const [onlyModeName, onlyValue] = Object.entries(token.values)[0] ?? [];
                 if (onlyValue) {
-                    const resolved = resolveValue(onlyValue, token, onlyModeName, tokenIndex, warnings);
+                    const resolved = resolveValue(onlyValue, token, onlyModeName, tokenIndex, warnings, dialect);
                     if (resolved !== undefined)
                         cursor[leafKey] = resolved;
                 }
@@ -152,7 +155,7 @@ function renderNested(sets, tokenIndex, warnings) {
 function pickPrimaryMode(modes) {
     return modes.find((m) => /^(default|light|value)$/i.test(m)) ?? modes[0];
 }
-function resolveValue(value, token, mode, tokenIndex, warnings) {
+function resolveValue(value, token, mode, tokenIndex, warnings, dialect) {
     let effective = value;
     if (value.reference) {
         effective = resolveAliasChain(value, mode, tokenIndex);
@@ -168,6 +171,21 @@ function resolveValue(value, token, mode, tokenIndex, warnings) {
     if (!effective || effective.literal === undefined || effective.literal === null) {
         return undefined;
     }
+    // DTCG 2025.10 dialect (opt-in): colors emit the object form, dimensions
+    // emit { value, unit: "px" }. Legacy (default) keeps hex strings and
+    // "16px" strings — byte-identical to historical output.
+    if (dialect === "2025") {
+        if (token.type === "color") {
+            const encoded = colorValueTo2025(effective);
+            if (encoded)
+                return encoded;
+        }
+        else if (token.type === "dimension") {
+            const encoded = dimensionLiteralTo2025(effective.literal);
+            if (encoded)
+                return encoded;
+        }
+    }
     if (typeof effective.literal === "number") {
         if (token.type === "dimension")
             return `${effective.literal}px`;

package/dist/cloudflare/core/tokens/formatters/scss.js

@@ -20,9 +20,13 @@
  * Composite tokens (typography, shadow) expand into multiple primitive
  * variables since SCSS variables hold a single value.
  */
+import { buildTokenIndex, referenceTargetPath } from "../alias-resolver.js";
 export function formatScss(doc, opts) {
     const warnings = [];
     const files = [];
+    // Whole-document index so set-qualified alias references resolve to the
+    // target token's own path when generating $variable names.
+    const tokenIndex = buildTokenIndex(doc, warnings);
     const splitByMode = opts.target.splitByMode ?? false;
     const splitByCollection = opts.target.splitByCollection ?? false;
     const prefix = opts.target.prefix ?? "";
@@ -31,7 +35,7 @@ export function formatScss(doc, opts) {
             for (const mode of set.modes) {
                 files.push({
                     path: filenameFor(opts, set, mode),
-                    content: renderSingleMode([set], mode, prefix, warnings),
+                    content: renderSingleMode([set], mode, prefix, tokenIndex, warnings),
                 });
             }
         }
@@ -45,7 +49,7 @@ export function formatScss(doc, opts) {
             const sets = doc.sets.filter((s) => s.modes.includes(mode));
             files.push({
                 path: filenameFor(opts, undefined, mode),
-                content: renderSingleMode(sets, mode, prefix, warnings),
+                content: renderSingleMode(sets, mode, prefix, tokenIndex, warnings),
             });
         }
     }
@@ -53,14 +57,14 @@ export function formatScss(doc, opts) {
         for (const set of doc.sets) {
             files.push({
                 path: filenameFor(opts, set),
-                content: renderAllModes([set], prefix, warnings),
+                content: renderAllModes([set], prefix, tokenIndex, warnings),
             });
         }
     }
     else {
         files.push({
             path: filenameFor(opts),
-            content: renderAllModes(doc.sets, prefix, warnings),
+            content: renderAllModes(doc.sets, prefix, tokenIndex, warnings),
         });
     }
     return { files, warnings };
@@ -87,7 +91,7 @@ function slugify(s) {
 function varName(path, prefix) {
     return `$${prefix}${path.map(slugify).join("-")}`;
 }
-function renderSingleMode(sets, mode, prefix, warnings) {
+function renderSingleMode(sets, mode, prefix, tokenIndex, warnings) {
     const lines = [];
     lines.push("// Generated by figma-console-mcp — do not edit by hand");
     lines.push(`// Mode: ${mode}`);
@@ -100,13 +104,13 @@ function renderSingleMode(sets, mode, prefix, warnings) {
             const value = token.values[mode];
             if (!value)
                 continue;
-            emitSassLines(token, value, prefix, lines, warnings);
+            emitSassLines(token, value, prefix, tokenIndex, lines, warnings);
         }
         lines.push("");
     }
     return lines.join("\n");
 }
-function renderAllModes(sets, prefix, warnings) {
+function renderAllModes(sets, prefix, tokenIndex, warnings) {
     const lines = [];
     lines.push("// Generated by figma-console-mcp — do not edit by hand");
     lines.push("");
@@ -120,7 +124,7 @@ function renderAllModes(sets, prefix, warnings) {
             // Primary value as the bare variable.
             const primary = token.values[primaryMode];
             if (primary)
-                emitSassLines(token, primary, prefix, lines, warnings);
+                emitSassLines(token, primary, prefix, tokenIndex, lines, warnings);
             // Other modes as a map: $ds-color-primary--modes: ("Dark": #..., "Vibrant": #...)
             if (isMultiMode) {
                 const otherModes = set.modes.filter((m) => m !== primaryMode);
@@ -129,7 +133,7 @@ function renderAllModes(sets, prefix, warnings) {
                     const v = token.values[mode];
                     if (!v)
                         continue;
-                    const formatted = scssValueFor(v, token, prefix, warnings);
+                    const formatted = scssValueFor(v, token, prefix, tokenIndex, warnings);
                     if (formatted !== null) {
                         entries.push(`  "${mode}": ${formatted}`);
                     }
@@ -149,7 +153,7 @@ function renderAllModes(sets, prefix, warnings) {
 function pickPrimaryMode(modes) {
     return modes.find((m) => /^(default|light|value)$/i.test(m)) ?? modes[0];
 }
-function emitSassLines(token, value, prefix, out, warnings) {
+function emitSassLines(token, value, prefix, tokenIndex, out, warnings) {
     const sassName = varName(token.path, prefix);
     if (value.reference) {
         const bareRef = value.reference.replace(/^\{|\}$/g, "");
@@ -160,7 +164,8 @@ function emitSassLines(token, value, prefix, out, warnings) {
             out.push(`// ${sassName}: skipped — cross-library alias to ${originalId}`);
             return;
         }
-        const refPath = bareRef.split(".");
+        // Resolve set-qualified references to the target token's own path.
+        const refPath = referenceTargetPath(value.reference, tokenIndex);
         out.push(`${sassName}: ${varName(refPath, prefix)};`);
         return;
     }
@@ -185,12 +190,13 @@ function emitSassLines(token, value, prefix, out, warnings) {
     }
     out.push(`${sassName}: ${formatScssLiteral(value.literal, token.type)};`);
 }
-function scssValueFor(value, token, prefix, _warnings) {
+function scssValueFor(value, token, prefix, tokenIndex, _warnings) {
     if (value.reference) {
         const bareRef = value.reference.replace(/^\{|\}$/g, "");
         if (bareRef.startsWith("__library:") || bareRef === "unknown")
             return null;
-        return varName(bareRef.split("."), prefix);
+        // Resolve set-qualified references to the target token's own path.
+        return varName(referenceTargetPath(value.reference, tokenIndex), prefix);
     }
     if (value.literal === undefined || value.literal === null)
         return null;

package/dist/cloudflare/core/tokens/formatters/style-dictionary-v3.js

@@ -39,9 +39,13 @@
  * For back-compat with cbds-components / blocks / czi-edu / eddie-design-system
  * which still use SD v3's bare-key source format.
  */
+import { buildTokenIndex, referenceTargetPath } from "../alias-resolver.js";
 export function formatStyleDictionaryV3(doc, opts) {
     const warnings = [];
     const files = [];
+    // Whole-document index so set-qualified alias references resolve to the
+    // target token's own path (SD v3 trees are path-based, no set groups).
+    const tokenIndex = buildTokenIndex(doc, warnings);
     const splitByMode = opts.target.splitByMode ?? false;
     const splitByCollection = opts.target.splitByCollection ?? false;
     if (splitByMode && splitByCollection) {
@@ -49,7 +53,7 @@ export function formatStyleDictionaryV3(doc, opts) {
             for (const mode of set.modes) {
                 files.push({
                     path: filenameFor(opts, set, mode),
-                    content: renderSdJson([set], [mode], warnings),
+                    content: renderSdJson([set], [mode], tokenIndex, warnings),
                 });
             }
         }
@@ -63,7 +67,7 @@ export function formatStyleDictionaryV3(doc, opts) {
             const sets = doc.sets.filter((s) => s.modes.includes(mode));
             files.push({
                 path: filenameFor(opts, undefined, mode),
-                content: renderSdJson(sets, [mode], warnings),
+                content: renderSdJson(sets, [mode], tokenIndex, warnings),
             });
         }
     }
@@ -71,7 +75,7 @@ export function formatStyleDictionaryV3(doc, opts) {
         for (const set of doc.sets) {
             files.push({
                 path: filenameFor(opts, set),
-                content: renderSdJson([set], set.modes, warnings),
+                content: renderSdJson([set], set.modes, tokenIndex, warnings),
             });
         }
     }
@@ -82,7 +86,7 @@ export function formatStyleDictionaryV3(doc, opts) {
                 allModes.add(m);
         files.push({
             path: filenameFor(opts),
-            content: renderSdJson(doc.sets, [...allModes], warnings),
+            content: renderSdJson(doc.sets, [...allModes], tokenIndex, warnings),
         });
     }
     return { files, warnings };
@@ -133,7 +137,7 @@ function sdTypeFor(token) {
     // Composites / less-common types: pass through.
     return token.type;
 }
-function renderSdJson(sets, modes, warnings) {
+function renderSdJson(sets, modes, tokenIndex, warnings) {
     const tree = {};
     const primaryMode = pickPrimaryMode(modes);
     for (const set of sets) {
@@ -150,7 +154,7 @@ function renderSdJson(sets, modes, warnings) {
                 ? primaryMode
                 : usableModes[0];
             const tokenValue = token.values[valueMode];
-            const sdValue = sdValueFor(tokenValue, token, warnings);
+            const sdValue = sdValueFor(tokenValue, token, tokenIndex, warnings);
             if (sdValue === undefined)
                 continue;
             // Walk the path, creating nested groups.
@@ -177,15 +181,17 @@ function renderSdJson(sets, modes, warnings) {
 function pickPrimaryMode(modes) {
     return modes.find((m) => /^(default|light|value)$/i.test(m)) ?? modes[0];
 }
-function sdValueFor(value, token, warnings) {
+function sdValueFor(value, token, tokenIndex, warnings) {
     if (value.reference) {
         const bare = value.reference.replace(/^\{|\}$/g, "");
         if (bare.startsWith("__library:") || bare === "unknown") {
             warnings.push(`Skipped ${token.path.join(".")} in Style Dictionary v3 — cross-library alias unresolved.`);
             return undefined;
         }
-        // SD v3 uses the same `{path.to.token}` alias syntax as DTCG.
-        return `{${bare}}`;
+        // SD v3 uses the same `{path.to.token}` alias syntax as DTCG, but its
+        // tree has no set groups — resolve set-qualified references to the
+        // target token's own path.
+        return `{${referenceTargetPath(value.reference, tokenIndex).join(".")}}`;
     }
     if (value.literal === undefined || value.literal === null)
         return undefined;