@mp3wizard/figma-console-mcp 1.23.1 → 1.27.2

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

@@ -0,0 +1,330 @@
+/**
+ * CSS custom properties formatter.
+ *
+ * Converts a TokenDocument to one or more CSS files containing `:root { ... }`
+ * (and optionally per-mode selectors like `.dark { ... }`). The first
+ * "real" non-DTCG output, completing the canonical-to-runtime pipeline.
+ *
+ * Behavior:
+ *   - Each token becomes a CSS custom property. Path joined with `-`,
+ *     optionally prefixed. `color/primary` → `--color-primary`.
+ *   - Aliases resolve to `var(--target-token)` so CSS cascading still works.
+ *   - Composite tokens (typography, shadow) expand into multiple primitive
+ *     custom properties since CSS doesn't natively express composites.
+ *   - Single-mode tokens go in `:root`.
+ *   - Multi-mode tokens emit per-mode selectors. Heuristic: a mode named
+ *     `Light`/`Default` becomes `:root`; `Dark` becomes `.dark` (Tailwind
+ *     convention); other modes become `[data-theme="<name>"]`.
+ *   - splitByMode emits one file per mode with just that mode's values.
+ *   - splitByCollection emits one file per set.
+ */
+export function formatCssVars(doc, opts) {
+    const warnings = [];
+    const files = [];
+    const splitByMode = opts.target.splitByMode ?? false;
+    const splitByCollection = opts.target.splitByCollection ?? false;
+    const prefix = opts.target.prefix ?? "";
+    if (splitByMode && splitByCollection) {
+        // One file per (set, mode) pair.
+        for (const set of doc.sets) {
+            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),
+                });
+            }
+        }
+    }
+    else if (splitByMode) {
+        // One file per mode, all sets combined under that mode's selector.
+        const allModes = new Set();
+        for (const set of doc.sets)
+            for (const m of set.modes)
+                allModes.add(m);
+        for (const mode of allModes) {
+            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),
+            });
+        }
+    }
+    else if (splitByCollection) {
+        // One file per set, all modes combined as separate selectors within.
+        for (const set of doc.sets) {
+            files.push({
+                path: filenameFor(opts, set),
+                content: renderMultiSelector([set], prefix, warnings),
+            });
+        }
+    }
+    else {
+        // Single file with everything.
+        files.push({
+            path: filenameFor(opts),
+            content: renderMultiSelector(doc.sets, prefix, warnings),
+        });
+    }
+    return { files, warnings };
+}
+function filenameFor(opts, set, mode) {
+    if (opts.target.filename)
+        return opts.target.filename;
+    const parts = [];
+    if (set)
+        parts.push(slugify(set.name));
+    if (mode)
+        parts.push(slugify(mode));
+    if (parts.length === 0)
+        parts.push("tokens");
+    return `${parts.join(".")}.css`;
+}
+function slugify(s) {
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Map a mode name to a CSS selector. Conventional defaults that match what
+ * most CSS frameworks expect:
+ *   - Default / Light / Value → `:root` (the document root, runs always)
+ *   - Dark → `.dark` (matches Tailwind's darkMode: "class" config)
+ *   - anything else → `[data-theme="<name>"]` (general escape hatch)
+ */
+function selectorFor(mode) {
+    const lower = mode.toLowerCase();
+    if (lower === "default" || lower === "light" || lower === "value") {
+        return ":root";
+    }
+    if (lower === "dark") {
+        return ".dark";
+    }
+    return `[data-theme="${slugify(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) {
+    const lines = [];
+    lines.push(`/* Generated by figma-console-mcp — do not edit by hand */`);
+    lines.push(`${selector} {`);
+    for (const set of sets) {
+        for (const token of set.tokens) {
+            const value = token.values[mode];
+            if (!value)
+                continue;
+            emitTokenLines(token, value, prefix, lines, warnings);
+        }
+    }
+    lines.push(`}`);
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Render multiple sets across multiple modes in one file. Each mode gets its
+ * own selector block.
+ */
+function renderMultiSelector(sets, prefix, warnings) {
+    const lines = [];
+    lines.push(`/* Generated by figma-console-mcp — do not edit by hand */`);
+    // Collect all (mode, selector) pairs across all sets.
+    const modeToSelector = new Map();
+    for (const set of sets) {
+        for (const mode of set.modes) {
+            if (!modeToSelector.has(mode)) {
+                modeToSelector.set(mode, selectorFor(mode));
+            }
+        }
+    }
+    for (const [mode, selector] of modeToSelector) {
+        lines.push(`${selector} {`);
+        for (const set of sets) {
+            if (!set.modes.includes(mode))
+                continue;
+            for (const token of set.tokens) {
+                const value = token.values[mode];
+                if (!value)
+                    continue;
+                emitTokenLines(token, value, prefix, lines, warnings);
+            }
+        }
+        lines.push(`}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Emit one or more CSS custom property declarations for a single token.
+ * Primitives emit one line; composite tokens (typography, shadow) expand
+ * into multiple lines.
+ */
+function emitTokenLines(token, value, prefix, 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").
+    const cssName = `--${prefix}${pathToCssName(token.path)}`;
+    if (value.reference) {
+        // Detect the cross-library alias sentinel ({__library:VariableID:...}).
+        // Emitting var() for these produces broken CSS — the target doesn't
+        // live in this file's variable set. Emit a clear comment that names
+        // the original library variable ID instead, so the user can decide
+        // how to handle it (manual literal, library import, etc.).
+        const bareRef = value.reference.replace(/^\{|\}$/g, "");
+        const libMatch = bareRef.match(/^__library:(.+)$/);
+        if (libMatch || bareRef === "unknown") {
+            const originalId = libMatch ? libMatch[1] : "unknown";
+            warnings.push(`Skipped ${token.path.join(".")} in CSS — references cross-library variable ${originalId}.`);
+            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(".");
+        const targetCssName = pathToCssName(refPath);
+        out.push(`  ${cssName}: var(--${prefix}${targetCssName});`);
+        return;
+    }
+    if (value.literal === undefined || value.literal === null) {
+        warnings.push(`Token ${token.path.join(".")} has no value — emitting nothing.`);
+        return;
+    }
+    // Composite tokens — expand into multiple primitive vars.
+    if (token.type === "typography" && typeof value.literal === "object") {
+        const t = value.literal;
+        for (const subField of ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing"]) {
+            if (t[subField] !== undefined) {
+                out.push(`  ${cssName}-${kebab(subField)}: ${formatCssValue(t[subField], token.type)};`);
+            }
+        }
+        return;
+    }
+    if (token.type === "shadow" && typeof value.literal === "object") {
+        const shadowCss = renderShadow(value.literal);
+        if (shadowCss) {
+            out.push(`  ${cssName}: ${shadowCss};`);
+        }
+        else {
+            warnings.push(`Token ${token.path.join(".")} has an unparseable shadow value — skipping.`);
+        }
+        return;
+    }
+    // Primitives.
+    out.push(`  ${cssName}: ${formatCssValue(value.literal, token.type)};`);
+}
+function kebab(s) {
+    return s.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+ * Convert a path array to a CSS-safe custom property name. Each segment is
+ * slugified (lowercase, non-alphanumerics → hyphens) before joining.
+ *
+ * Examples:
+ *   ["color", "primary"]                  → "color-primary"
+ *   ["tailwind colors", "purple", "50"]   → "tailwind-colors-purple-50"
+ *   ["UI", "background-default"]          → "ui-background-default"
+ */
+function pathToCssName(path) {
+    return path.map((seg) => slugify(seg)).join("-");
+}
+/**
+ * Render a primitive value as a CSS literal.
+ *   - Numbers gain a "px" suffix when the token type is `dimension`.
+ *   - Color-typed strings pass through (hex, oklch, rgba, hsl).
+ *   - fontFamily-typed strings get quoted (multi-word family names are
+ *     invalid CSS otherwise — e.g. "Geist Mono" must be `"Geist Mono"`).
+ *   - Plain string tokens get quoted too, since CSS treats unquoted
+ *     identifiers as keywords. Strings that look like a CSS color or unit
+ *     stay unquoted.
+ *   - Booleans render as their string form.
+ */
+function formatCssValue(value, type) {
+    if (typeof value === "number") {
+        if (type === "dimension")
+            return `${value}px`;
+        return String(value);
+    }
+    if (typeof value === "string") {
+        // Color-typed values are always pre-formatted CSS color literals.
+        if (type === "color")
+            return value;
+        // fontFamily and plain strings need quoting unless they look like a
+        // CSS-safe identifier with no special characters. Quote conservatively
+        // — over-quoting is fine, under-quoting breaks the cascade.
+        if (type === "fontFamily" || type === "string") {
+            return needsQuoting(value) ? JSON.stringify(value) : value;
+        }
+        // Dimensions and other types: pass through (already formatted upstream).
+        return value;
+    }
+    if (typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+/**
+ * Returns true if a string value needs to be wrapped in CSS quotes. Multi-word
+ * values, values with special characters, or values that aren't pure
+ * alphanumeric identifiers all need quoting.
+ */
+function needsQuoting(s) {
+    // Anything that already has quotes is fine.
+    if (/^["']/.test(s))
+        return false;
+    // Pure-numeric or unit-bearing values don't need quotes (they're not
+    // identifiers).
+    if (/^[\d.]+([a-z%]+)?$/.test(s))
+        return false;
+    // CSS keyword identifiers (single word, alphanumerics + hyphen only).
+    if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(s)) {
+        // Reserved CSS keywords that shouldn't be quoted (the user may have
+        // legitimately written e.g. "inherit", "currentColor", "transparent").
+        const cssKeywords = new Set([
+            "inherit",
+            "initial",
+            "unset",
+            "revert",
+            "currentColor",
+            "transparent",
+            "none",
+            "auto",
+        ]);
+        if (cssKeywords.has(s))
+            return false;
+        // Any other single identifier — for font-family this is OK unquoted
+        // ("Inter" works) but it's safer to quote for clarity. Keep unquoted
+        // to match the more common convention.
+        return false;
+    }
+    // Multi-word, special chars, etc. → quote.
+    return true;
+}
+function renderShadow(shadow) {
+    if (Array.isArray(shadow)) {
+        return shadow
+            .map((s) => renderShadow(s))
+            .filter(Boolean)
+            .join(", ");
+    }
+    if (!shadow || typeof shadow !== "object")
+        return null;
+    const s = shadow;
+    const inset = s.inset ? "inset " : "";
+    const x = withPx(s.offsetX);
+    const y = withPx(s.offsetY);
+    const blur = withPx(s.blur);
+    const spread = s.spread !== undefined ? ` ${withPx(s.spread)}` : "";
+    const color = s.color;
+    if (!x || !y || !blur || typeof color !== "string")
+        return null;
+    return `${inset}${x} ${y} ${blur}${spread} ${color}`;
+}
+function withPx(v) {
+    if (typeof v === "number")
+        return `${v}px`;
+    if (typeof v === "string")
+        return v;
+    return "";
+}
+//# sourceMappingURL=css-vars.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"css-vars.js","sourceRoot":"","sources":["../../../../src/core/tokens/formatters/css-vars.ts"],"names":[],"mappings":"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"}

package/dist/core/tokens/formatters/dtcg.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DTCG (Design Tokens Community Group) JSON formatter.
+ *
+ * Produces W3C-spec DTCG output (https://tr.designtokens.org/format/) with
+ * three nuances:
+ *
+ *   1. Multi-mode tokens. The DTCG v1 spec doesn't natively express modes;
+ *      we use a separate file per mode (driven by `splitByMode: true`) or a
+ *      single file with values keyed by mode under a vendor extension when
+ *      splitByMode is false. The split-file approach is the recommended
+ *      pattern in the broader DTCG community and is what Style Dictionary
+ *      v4, Tokens Studio, and Figma's announced native export all use.
+ *
+ *   2. $extensions["figma-console-mcp"]. We stash Figma variable IDs and
+ *      last-synced values here for non-destructive round-trip. Other DTCG
+ *      tools preserve $extensions verbatim.
+ *
+ *   3. Composite tokens (typography, shadow, gradient) emit DTCG's
+ *      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.
+ */
+import type { TokenDocument } from "../types.js";
+import type { FormatOptions, FormatResult } from "./index.js";
+export declare function formatDtcg(doc: TokenDocument, opts: FormatOptions): FormatResult;
+//# sourceMappingURL=dtcg.d.ts.map

package/dist/core/tokens/formatters/dtcg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dtcg.d.ts","sourceRoot":"","sources":["../../../../src/core/tokens/formatters/dtcg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAEV,aAAa,EAGd,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAoB9D,wBAAgB,UAAU,CACxB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,aAAa,GAClB,YAAY,CA+Dd"}

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

@@ -0,0 +1,301 @@
+/**
+ * DTCG (Design Tokens Community Group) JSON formatter.
+ *
+ * Produces W3C-spec DTCG output (https://tr.designtokens.org/format/) with
+ * three nuances:
+ *
+ *   1. Multi-mode tokens. The DTCG v1 spec doesn't natively express modes;
+ *      we use a separate file per mode (driven by `splitByMode: true`) or a
+ *      single file with values keyed by mode under a vendor extension when
+ *      splitByMode is false. The split-file approach is the recommended
+ *      pattern in the broader DTCG community and is what Style Dictionary
+ *      v4, Tokens Studio, and Figma's announced native export all use.
+ *
+ *   2. $extensions["figma-console-mcp"]. We stash Figma variable IDs and
+ *      last-synced values here for non-destructive round-trip. Other DTCG
+ *      tools preserve $extensions verbatim.
+ *
+ *   3. Composite tokens (typography, shadow, gradient) emit DTCG's
+ *      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.
+ */
+import { FIGMA_MCP_EXTENSION_KEY } from "../types.js";
+import { formatDtcgReference } from "../alias-resolver.js";
+export function formatDtcg(doc, opts) {
+    const warnings = [];
+    const files = [];
+    // Figure out which sets and modes to emit, and how they map to files.
+    // Three layout strategies:
+    //   1. splitByMode + splitByCollection → one file per (set, mode) pair
+    //   2. splitByMode → one file per mode, all sets merged
+    //   3. splitByCollection → one file per set, all modes in one tree
+    //   4. neither → one file with everything
+    const splitByMode = opts.target.splitByMode ?? false;
+    const splitByCollection = opts.target.splitByCollection ?? false;
+    if (splitByMode && splitByCollection) {
+        for (const set of doc.sets) {
+            for (const mode of set.modes) {
+                const fileTokens = set.tokens
+                    .map((t) => projectTokenToMode(t, mode, warnings))
+                    .filter((t) => t !== null);
+                files.push({
+                    path: filenameFor(opts, set, mode),
+                    content: serializeAsDtcg({ sets: [{ ...set, modes: [mode], tokens: fileTokens }], meta: doc.meta }, warnings, mode),
+                });
+            }
+        }
+    }
+    else if (splitByMode) {
+        const allModes = new Set();
+        for (const set of doc.sets)
+            for (const m of set.modes)
+                allModes.add(m);
+        for (const mode of allModes) {
+            const fileSets = doc.sets
+                .filter((s) => s.modes.includes(mode))
+                .map((s) => ({
+                ...s,
+                modes: [mode],
+                tokens: s.tokens
+                    .map((t) => projectTokenToMode(t, mode, warnings))
+                    .filter((t) => t !== null),
+            }));
+            files.push({
+                path: filenameFor(opts, undefined, mode),
+                content: serializeAsDtcg({ sets: fileSets, meta: doc.meta }, warnings, mode),
+            });
+        }
+    }
+    else if (splitByCollection) {
+        for (const set of doc.sets) {
+            files.push({
+                path: filenameFor(opts, set),
+                content: serializeAsDtcg({ sets: [set], meta: doc.meta }, warnings),
+            });
+        }
+    }
+    else {
+        files.push({
+            path: filenameFor(opts),
+            content: serializeAsDtcg(doc, warnings),
+        });
+    }
+    return { files, warnings };
+}
+/**
+ * Project a token's values down to a single mode. Returns null if the token
+ * has no value for the requested mode (skip rather than emit a blank).
+ */
+function projectTokenToMode(token, mode, warnings) {
+    const value = token.values[mode];
+    if (!value) {
+        // Token wasn't defined for this mode. Could happen when sets share tokens
+        // but only some have multi-mode values. Skip silently — not an error.
+        return null;
+    }
+    return { ...token, values: { [mode]: value } };
+}
+/**
+ * Compute the output filename for a given (set?, mode?) tuple based on the
+ * target options.
+ */
+function filenameFor(opts, set, mode) {
+    // Caller-specified filename wins.
+    if (opts.target.filename)
+        return opts.target.filename;
+    const parts = [];
+    if (set)
+        parts.push(slugify(set.name));
+    if (mode)
+        parts.push(slugify(mode));
+    if (parts.length === 0)
+        parts.push("tokens");
+    return `${parts.join(".")}.tokens.json`;
+}
+function slugify(s) {
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Serialize a TokenDocument as DTCG JSON. Returns a pretty-printed JSON string
+ * with stable key order so git diffs stay minimal across runs.
+ *
+ * When `fileMode` is provided (splitByMode output), it's stamped into
+ * document-level $extensions so the parser can recover which mode this
+ * 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) {
+    // Build the nested DTCG group tree by walking every token's path and
+    // building groups along the way.
+    const tree = {};
+    // Document-level $extensions: stash file-level metadata (Figma file key,
+    // export timestamp, MCP version, optionally the file's mode for
+    // splitByMode output) so round-trip preserves it.
+    const mcpDocMeta = {};
+    if (doc.meta?.figmaFileKey)
+        mcpDocMeta.figmaFileKey = doc.meta.figmaFileKey;
+    if (doc.meta?.exportedAt)
+        mcpDocMeta.exportedAt = doc.meta.exportedAt;
+    if (doc.meta?.mcpVersion)
+        mcpDocMeta.mcpVersion = doc.meta.mcpVersion;
+    if (fileMode)
+        mcpDocMeta.fileMode = fileMode;
+    if (Object.keys(mcpDocMeta).length > 0) {
+        tree.$extensions = { [FIGMA_MCP_EXTENSION_KEY]: mcpDocMeta };
+    }
+    for (const set of doc.sets) {
+        // Each set lives under a top-level group named after the set. Set-level
+        // metadata (Figma collection ID, original name, etc.) goes in that
+        // group's $extensions so round-trip recovers the original name even
+        // after we slugify it for the JSON key.
+        const setKey = setKeyFor(set);
+        let setGroup = tree[setKey];
+        if (!setGroup) {
+            setGroup = {};
+            if (set.description)
+                setGroup.$description = set.description;
+            const mcpMeta = {};
+            if (set.meta?.figmaCollectionId) {
+                mcpMeta.figmaCollectionId = set.meta.figmaCollectionId;
+            }
+            // Always stash the original name when it differs from the slug — this
+            // is what makes diff matching work after round-trip.
+            if (set.name !== setKey) {
+                mcpMeta.originalName = set.name;
+            }
+            if (Object.keys(mcpMeta).length > 0) {
+                setGroup.$extensions = { [FIGMA_MCP_EXTENSION_KEY]: mcpMeta };
+            }
+            tree[setKey] = setGroup;
+        }
+        for (const token of set.tokens) {
+            writeTokenIntoTree(setGroup, token, set.modes, warnings);
+        }
+    }
+    return JSON.stringify(sortKeys(tree), null, 2) + "\n";
+}
+/**
+ * Key used for the top-level set group in DTCG. We slugify the set name to
+ * keep it a valid JSON key under any consumer's expectations. The original
+ * (un-slugged) name is preserved in the set's $extensions so round-trip
+ * recovers it.
+ */
+function setKeyFor(set) {
+    return slugify(set.name);
+}
+/**
+ * Insert a token into the DTCG group tree at the right nested path.
+ * Creates intermediate groups as needed.
+ */
+function writeTokenIntoTree(root, token, setModes, warnings) {
+    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)) {
+            next = {};
+            cursor[segment] = next;
+        }
+        cursor = next;
+    }
+    const leafKey = token.path[token.path.length - 1];
+    cursor[leafKey] = renderToken(token, setModes, warnings);
+}
+function isToken(node) {
+    return "$value" in 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.
+ */
+function renderToken(token, setModes, warnings) {
+    const result = {
+        $value: "",
+        $type: token.type,
+    };
+    if (token.description)
+        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 = {};
+        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);
+        }
+    }
+    // Preserve any pre-existing extensions (e.g. studio.tokens, our own metadata).
+    if (token.extensions) {
+        for (const [vendor, payload] of Object.entries(token.extensions)) {
+            if (vendor === FIGMA_MCP_EXTENSION_KEY) {
+                mergeExtension(result, vendor, payload);
+            }
+            else {
+                mergeExtension(result, vendor, payload);
+            }
+        }
+    }
+    return result;
+}
+function encodeValue(value, token, warnings) {
+    if (value.reference) {
+        return formatDtcgReference(value.reference.replace(/^\{|\}$/g, "").split("."));
+    }
+    if (value.literal === undefined) {
+        warnings.push(`Token ${token.path.join(".")} has neither literal nor reference — emitting empty string.`);
+        return "";
+    }
+    return value.literal;
+}
+function mergeExtension(token, key, payload) {
+    token.$extensions ??= {};
+    token.$extensions[key] = payload;
+}
+/**
+ * Recursively sort object keys for stable serialization (so git diffs only
+ * show meaningful changes). $-prefixed keys come first (DTCG convention),
+ * then alphabetical.
+ */
+function sortKeys(node) {
+    if (node === null || typeof node !== "object" || Array.isArray(node)) {
+        return node;
+    }
+    const obj = node;
+    const sorted = {};
+    const keys = Object.keys(obj).sort((a, b) => {
+        const aDollar = a.startsWith("$");
+        const bDollar = b.startsWith("$");
+        if (aDollar && !bDollar)
+            return -1;
+        if (!aDollar && bDollar)
+            return 1;
+        return a.localeCompare(b);
+    });
+    for (const k of keys)
+        sorted[k] = sortKeys(obj[k]);
+    return sorted;
+}
+//# sourceMappingURL=dtcg.js.map