@mp3wizard/figma-console-mcp 1.23.1 → 1.27.2

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

@@ -0,0 +1,11 @@
+/**
+ * Shared NotImplementedError used by formatter stubs. DTCG JSON and CSS
+ * custom properties are the fully-implemented formatters; everything else
+ * is scaffolded and throws this error.
+ */
+export class FormatterNotImplementedError extends Error {
+    constructor(formatName) {
+        super(`[figma-console-mcp] The ${formatName} formatter is scaffolded but not yet implemented. Fully implemented formats: 'dtcg' (canonical W3C JSON) and 'css-vars' (CSS custom properties with mode-aware selectors). For other targets, export to 'dtcg' and either consume the canonical JSON directly or convert it via a downstream tool — or open an issue with your styling stack to prioritize the format.`);
+        this.name = "FormatterNotImplementedError";
+    }
+}

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

@@ -0,0 +1,4 @@
+import { FormatterNotImplementedError } from "./stubs.js";
+export function formatStyleDictionaryV3(_doc, _opts) {
+    throw new FormatterNotImplementedError("Style Dictionary v3");
+}

package/dist/cloudflare/core/tokens/formatters/tailwind-v3.js

@@ -0,0 +1,4 @@
+import { FormatterNotImplementedError } from "./stubs.js";
+export function formatTailwindV3(_doc, _opts) {
+    throw new FormatterNotImplementedError("Tailwind v3 config");
+}

package/dist/cloudflare/core/tokens/formatters/tailwind-v4.js

@@ -0,0 +1,4 @@
+import { FormatterNotImplementedError } from "./stubs.js";
+export function formatTailwindV4(_doc, _opts) {
+    throw new FormatterNotImplementedError("Tailwind v4 @theme");
+}

package/dist/cloudflare/core/tokens/formatters/tokens-studio.js

@@ -0,0 +1,4 @@
+import { FormatterNotImplementedError } from "./stubs.js";
+export function formatTokensStudio(_doc, _opts) {
+    throw new FormatterNotImplementedError("Tokens Studio");
+}

package/dist/cloudflare/core/tokens/formatters/ts-module.js

@@ -0,0 +1,4 @@
+import { FormatterNotImplementedError } from "./stubs.js";
+export function formatTsModule(_doc, _opts) {
+    throw new FormatterNotImplementedError("TypeScript module");
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Public surface of the token sync engine.
+ *
+ * Re-exports the canonical types, the parser/formatter dispatchers, the
+ * config loader, the alias resolver, and the Figma converter. External
+ * callers (tools, tests) should import from here rather than reaching into
+ * subdirectories.
+ */
+export { FIGMA_MCP_EXTENSION_KEY } from "./types.js";
+export { TokensConfigSchema, loadTokensConfig, findTokensConfig, DEFAULT_TOKENS_CONFIG, buildSuggestedScaffold, resolveOutputTargets, resolveConflictStrategy, } from "./config.js";
+export { ExportTokensInputSchema, ImportTokensInputSchema, ExportFormatSchema, ImportFormatSchema, SyncStrategySchema, ConflictResolutionSchema, } from "./schemas.js";
+export { parse, detectFormat, } from "./parsers/index.js";
+export { format, } from "./formatters/index.js";
+export { buildTokenIndex, resolveReference, validateAliases, formatDtcgReference, parseDtcgReference, } from "./alias-resolver.js";
+export { convertFigmaVariablesToDocument, } from "./figma-converter.js";

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

@@ -0,0 +1,4 @@
+import { TokenFormatNotImplementedError } from "./stubs.js";
+export function parseCssVars(_input) {
+    throw new TokenFormatNotImplementedError("CSS custom properties", "parser");
+}

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

@@ -0,0 +1,253 @@
+/**
+ * DTCG (Design Tokens Community Group) JSON parser.
+ *
+ * Reads DTCG-spec JSON (https://tr.designtokens.org/format/) and produces our
+ * canonical internal TokenDocument. Designed for non-destructive round-trip:
+ * a document serialized by `formatDtcg` then parsed back through this module
+ * is equal to the original (modulo key ordering, which the formatter sorts
+ * for stable diffs).
+ *
+ * Handles:
+ *   - Group nesting with arbitrary depth
+ *   - $value / $type / $description / $extensions on leaf tokens
+ *   - Alias references: `"$value": "{path.to.token}"`
+ *   - Group-level $type inheritance per the DTCG spec (tokens without their
+ *     own $type inherit from their nearest ancestor group that has one)
+ *   - Our $extensions["figma-console-mcp"] metadata for round-trip ID preservation
+ *   - Multi-mode tokens stashed in $extensions.modes by our formatter
+ */
+import { FIGMA_MCP_EXTENSION_KEY } from "../types.js";
+import { parseDtcgReference } from "../alias-resolver.js";
+const DTCG_TYPES = new Set([
+    "color",
+    "dimension",
+    "fontFamily",
+    "fontWeight",
+    "duration",
+    "cubicBezier",
+    "number",
+    "string",
+    "boolean",
+    "shadow",
+    "typography",
+    "gradient",
+    "border",
+    "transition",
+    "strokeStyle",
+]);
+export function parseDtcg(input) {
+    const warnings = [];
+    const root = parseJson(input);
+    // Document-level $extensions: pull out our MCP metadata if present.
+    // `fileMode` is the critical piece for splitByMode round-trip — when set,
+    // every token in the file represents that mode's value, so we label them
+    // accordingly instead of falling back to "Default".
+    const meta = {};
+    let fileMode;
+    const rootExt = root.$extensions;
+    if (rootExt && typeof rootExt === "object") {
+        const mcpMeta = rootExt[FIGMA_MCP_EXTENSION_KEY];
+        if (mcpMeta && typeof mcpMeta === "object") {
+            const m = mcpMeta;
+            if (typeof m.figmaFileKey === "string")
+                meta.figmaFileKey = m.figmaFileKey;
+            if (typeof m.exportedAt === "string")
+                meta.exportedAt = m.exportedAt;
+            if (typeof m.mcpVersion === "string")
+                meta.mcpVersion = m.mcpVersion;
+            if (typeof m.fileMode === "string")
+                fileMode = m.fileMode;
+        }
+    }
+    // Each top-level group is a TokenSet. Walk it to extract its tokens.
+    const sets = [];
+    for (const [setKey, setNode] of Object.entries(root)) {
+        if (setKey.startsWith("$"))
+            continue; // $extensions etc.
+        if (!setNode || typeof setNode !== "object") {
+            warnings.push(`Top-level entry "${setKey}" is not a group; skipping. Expected object.`);
+            continue;
+        }
+        sets.push(extractSet(setKey, setNode, warnings, fileMode));
+    }
+    return {
+        document: {
+            $schema: "https://figma-console-mcp.southleft.com/schemas/dtcg-extended-v1.json",
+            sets,
+            meta: Object.keys(meta).length > 0 ? meta : undefined,
+        },
+        detectedFormat: "dtcg",
+        warnings,
+    };
+}
+function parseJson(input) {
+    try {
+        return JSON.parse(input.payload);
+    }
+    catch (err) {
+        throw new Error(`[figma-console-mcp] Failed to parse DTCG JSON${input.sourcePath ? ` at ${input.sourcePath}` : ""}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function extractSet(setKey, setNode, warnings, fileMode) {
+    const tokens = [];
+    const modes = new Set();
+    // Set-level metadata pulled from $extensions["figma-console-mcp"]. We
+    // recover the original (un-slugified) set name from `originalName` so
+    // round-trip matching works even after slugification.
+    const setExt = setNode.$extensions;
+    let figmaCollectionId;
+    let originalName;
+    if (setExt && typeof setExt === "object") {
+        const mcp = setExt[FIGMA_MCP_EXTENSION_KEY];
+        if (mcp && typeof mcp === "object") {
+            const m = mcp;
+            if (typeof m.figmaCollectionId === "string") {
+                figmaCollectionId = m.figmaCollectionId;
+            }
+            if (typeof m.originalName === "string") {
+                originalName = m.originalName;
+            }
+        }
+    }
+    // Walk the set's tree, collecting tokens.
+    walkGroup(setNode, [], undefined, tokens, modes, warnings, fileMode);
+    return {
+        name: originalName ?? setKey,
+        description: typeof setNode.$description === "string" ? setNode.$description : undefined,
+        modes: modes.size > 0 ? [...modes] : ["Default"],
+        tokens,
+        meta: figmaCollectionId ? { figmaCollectionId } : undefined,
+    };
+}
+function walkGroup(node, path, inheritedType, tokens, modes, warnings, fileMode) {
+    // Group-level $type provides inheritance for descendant tokens that lack
+    // their own $type, per the DTCG spec.
+    const groupType = typeof node.$type === "string" && DTCG_TYPES.has(node.$type)
+        ? node.$type
+        : inheritedType;
+    for (const [key, value] of Object.entries(node)) {
+        if (key.startsWith("$"))
+            continue;
+        if (!value || typeof value !== "object") {
+            warnings.push(`Non-group, non-token entry at ${[...path, key].join(".")}; skipping.`);
+            continue;
+        }
+        const childPath = [...path, key];
+        if (isLeafToken(value)) {
+            const token = extractToken(childPath, value, groupType, warnings, fileMode);
+            tokens.push(token);
+            for (const mode of Object.keys(token.values))
+                modes.add(mode);
+        }
+        else {
+            walkGroup(value, childPath, groupType, tokens, modes, warnings, fileMode);
+        }
+    }
+}
+function isLeafToken(node) {
+    return "$value" in node;
+}
+function extractToken(path, node, inheritedType, warnings, fileMode) {
+    const rawType = node.$type;
+    let type;
+    if (typeof rawType === "string" && DTCG_TYPES.has(rawType)) {
+        type = rawType;
+    }
+    else if (inheritedType) {
+        type = inheritedType;
+    }
+    else {
+        type = inferType(node.$value);
+        warnings.push(`Token ${path.join(".")} has no $type and no group $type inherited; inferred "${type}".`);
+    }
+    const description = typeof node.$description === "string" ? node.$description : undefined;
+    // Detect multi-mode stashed in $extensions.{FIGMA_MCP_EXTENSION_KEY}.modes
+    // (placed there by our own formatter for one-file-multi-mode output).
+    const values = {};
+    const ext = node.$extensions;
+    const mcpExt = ext && typeof ext === "object"
+        ? ext[FIGMA_MCP_EXTENSION_KEY]
+        : undefined;
+    const stashedModes = mcpExt?.modes;
+    // Decide which mode name to assign to the primary $value.
+    //   1. If the file declares a fileMode (splitByMode output), use that.
+    //   2. Otherwise fall back to "Default" — the parser can't know the
+    //      mode without that hint.
+    // Then absorb any stashedModes (one-file-multi-mode output) verbatim.
+    const primaryMode = fileMode ?? "Default";
+    values[primaryMode] = decodeValue(node.$value);
+    if (stashedModes) {
+        for (const [modeName, modeValue] of Object.entries(stashedModes)) {
+            // Don't overwrite the primary if a stashed entry collides with it.
+            if (modeName !== primaryMode) {
+                values[modeName] = decodeValue(modeValue);
+            }
+        }
+    }
+    // Preserve all other vendor extensions verbatim.
+    let extensions;
+    if (ext && typeof ext === "object") {
+        extensions = {};
+        for (const [vendor, payload] of Object.entries(ext)) {
+            if (vendor === FIGMA_MCP_EXTENSION_KEY &&
+                payload &&
+                typeof payload === "object") {
+                // Strip the "modes" we already absorbed into values.
+                const cleaned = { ...payload };
+                delete cleaned.modes;
+                if (Object.keys(cleaned).length > 0) {
+                    extensions[vendor] = cleaned;
+                }
+            }
+            else {
+                extensions[vendor] = payload;
+            }
+        }
+        if (Object.keys(extensions).length === 0)
+            extensions = undefined;
+    }
+    return {
+        path,
+        type,
+        description,
+        values,
+        extensions,
+    };
+}
+/**
+ * Convert a DTCG $value to our internal TokenValue. Detects alias references
+ * (strings of the form `{path.to.token}`) and unwraps them into TokenValue.reference.
+ */
+function decodeValue(rawValue) {
+    if (typeof rawValue === "string") {
+        const refPath = parseDtcgReference(rawValue);
+        if (refPath) {
+            return { reference: rawValue };
+        }
+        return { literal: rawValue };
+    }
+    if (rawValue === null ||
+        typeof rawValue === "number" ||
+        typeof rawValue === "boolean") {
+        return { literal: rawValue ?? "" };
+    }
+    // Composite values (typography, shadow, etc.) — preserve verbatim.
+    return { literal: rawValue };
+}
+function inferType(rawValue) {
+    if (typeof rawValue === "string") {
+        // Heuristics: color-ish strings → color; px/rem/em → dimension; else string.
+        if (/^#[0-9a-f]{3,8}$/i.test(rawValue))
+            return "color";
+        if (/^(rgb|hsl|oklch)/i.test(rawValue))
+            return "color";
+        if (/^[\d.]+(px|rem|em|pt|dp)$/i.test(rawValue))
+            return "dimension";
+        return "string";
+    }
+    if (typeof rawValue === "number")
+        return "number";
+    if (typeof rawValue === "boolean")
+        return "boolean";
+    return "string";
+}

package/dist/cloudflare/core/tokens/parsers/index.js

@@ -0,0 +1,138 @@
+/**
+ * Parser dispatcher. Each parser converts an input format into our canonical
+ * internal TokenDocument model.
+ */
+import { parseDtcg } from "./dtcg.js";
+import { parseTokensStudio } from "./tokens-studio.js";
+import { parseCssVars } from "./css-vars.js";
+import { parseTailwindV4 } from "./tailwind-v4.js";
+import { parseTailwindV3Config } from "./tailwind-v3.js";
+import { parseScss } from "./scss.js";
+import { parseStyleDictionaryV3 } from "./style-dictionary-v3.js";
+import { parseJsonFlat, parseJsonNested } from "./json.js";
+/**
+ * Parse a payload using the given format. When format is 'auto', sniffs the
+ * payload to pick the right parser.
+ */
+export function parse(format, input) {
+    const resolved = format === "auto" ? detectFormat(input) : format;
+    switch (resolved) {
+        case "dtcg":
+            return parseDtcg(input);
+        case "tokens-studio":
+            return parseTokensStudio(input);
+        case "css-vars":
+            return parseCssVars(input);
+        case "tailwind-v4":
+            return parseTailwindV4(input);
+        case "tailwind-v3-config":
+            return parseTailwindV3Config(input);
+        case "scss":
+            return parseScss(input);
+        case "style-dictionary-v3":
+            return parseStyleDictionaryV3(input);
+        case "json-flat":
+            return parseJsonFlat(input);
+        case "json-nested":
+            return parseJsonNested(input);
+        default: {
+            const _exhaustive = resolved;
+            throw new Error(`[figma-console-mcp] Unknown import format: ${_exhaustive}`);
+        }
+    }
+}
+/**
+ * Sniff the payload to determine its format. Order matters — earlier checks
+ * are higher-priority signals.
+ *
+ *  1. JSON content with DTCG markers ($value/$type at any depth)
+ *  2. JSON content with Tokens Studio markers ($themes.json or $metadata)
+ *  3. JSON content with Style Dictionary v3 markers (bare value/type)
+ *  4. Tailwind v4 `@theme` block
+ *  5. CSS custom properties (`:root { --foo: bar; }`)
+ *  6. SCSS variables (`$foo: bar;`)
+ *  7. File extension as a last-resort hint
+ */
+export function detectFormat(input) {
+    const trimmed = input.payload.trim();
+    // JSON-shape sniffing
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (hasDtcgMarkers(parsed))
+                return "dtcg";
+            if (hasTokensStudioMarkers(parsed))
+                return "tokens-studio";
+            if (hasStyleDictionaryV3Markers(parsed))
+                return "style-dictionary-v3";
+            if (looksFlat(parsed))
+                return "json-flat";
+            return "json-nested";
+        }
+        catch {
+            // Not actually JSON — fall through to text sniffing.
+        }
+    }
+    // Tailwind v4: presence of `@theme` directive
+    if (trimmed.includes("@theme"))
+        return "tailwind-v4";
+    // CSS custom properties
+    if (/--[a-z][a-z0-9_-]*\s*:/i.test(trimmed))
+        return "css-vars";
+    // SCSS variables
+    if (/^\s*\$[a-z][a-z0-9_-]*\s*:/im.test(trimmed))
+        return "scss";
+    // File extension fallback
+    if (input.sourcePath) {
+        if (input.sourcePath.endsWith(".css"))
+            return "css-vars";
+        if (input.sourcePath.endsWith(".scss"))
+            return "scss";
+        if (input.sourcePath.endsWith(".json"))
+            return "json-nested";
+    }
+    throw new Error(`[figma-console-mcp] Unable to auto-detect format for ${input.sourcePath ?? "payload"}. Pass an explicit format to figma_import_tokens.`);
+}
+function hasDtcgMarkers(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    for (const key of Object.keys(obj)) {
+        const val = obj[key];
+        if (key === "$value" || key === "$type")
+            return true;
+        if (val && typeof val === "object" && hasDtcgMarkers(val))
+            return true;
+    }
+    return false;
+}
+function hasTokensStudioMarkers(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const top = obj;
+    // Tokens Studio's signature: presence of $themes or $metadata at the root,
+    // or selectedTokenSets nested inside the document.
+    return ("$themes" in top ||
+        "$metadata" in top ||
+        JSON.stringify(top).includes("selectedTokenSets"));
+}
+function hasStyleDictionaryV3Markers(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    // SD v3 uses bare "value" and "type" fields (no $ prefix) on leaf nodes.
+    for (const val of Object.values(obj)) {
+        if (val && typeof val === "object") {
+            const inner = val;
+            if ("value" in inner && ("type" in inner || typeof inner.value !== "object")) {
+                return true;
+            }
+            if (hasStyleDictionaryV3Markers(val))
+                return true;
+        }
+    }
+    return false;
+}
+function looksFlat(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    return Object.values(obj).every((v) => typeof v !== "object" || v === null);
+}

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

@@ -0,0 +1,7 @@
+import { TokenFormatNotImplementedError } from "./stubs.js";
+export function parseJsonFlat(_input) {
+    throw new TokenFormatNotImplementedError("flat JSON", "parser");
+}
+export function parseJsonNested(_input) {
+    throw new TokenFormatNotImplementedError("nested JSON", "parser");
+}

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

@@ -0,0 +1,4 @@
+import { TokenFormatNotImplementedError } from "./stubs.js";
+export function parseScss(_input) {
+    throw new TokenFormatNotImplementedError("SCSS variables", "parser");
+}

package/dist/cloudflare/core/tokens/parsers/stubs.js

@@ -0,0 +1,13 @@
+/**
+ * Shared NotImplementedError for parsers/formatters that are scaffolded but
+ * not yet implemented. DTCG round-trip is the canonical fully-implemented
+ * path; CSS variables is also fully implemented as a formatter output.
+ * Everything else returns a helpful error pointing the user at the canonical
+ * format.
+ */
+export class TokenFormatNotImplementedError extends Error {
+    constructor(formatName, kind) {
+        super(`[figma-console-mcp] The ${formatName} ${kind} is scaffolded but not yet implemented. Fully implemented: DTCG JSON (parser + formatter) and CSS custom properties (formatter only). For now, export to 'dtcg' as the canonical format and either consume the JSON directly or convert downstream — or open an issue with your use case to prioritize this format.`);
+        this.name = "TokenFormatNotImplementedError";
+    }
+}

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

@@ -0,0 +1,4 @@
+import { TokenFormatNotImplementedError } from "./stubs.js";
+export function parseStyleDictionaryV3(_input) {
+    throw new TokenFormatNotImplementedError("Style Dictionary v3", "parser");
+}

package/dist/cloudflare/core/tokens/parsers/tailwind-v3.js

@@ -0,0 +1,4 @@
+import { TokenFormatNotImplementedError } from "./stubs.js";
+export function parseTailwindV3Config(_input) {
+    throw new TokenFormatNotImplementedError("Tailwind v3 config", "parser");
+}

package/dist/cloudflare/core/tokens/parsers/tailwind-v4.js

@@ -0,0 +1,4 @@
+import { TokenFormatNotImplementedError } from "./stubs.js";
+export function parseTailwindV4(_input) {
+    throw new TokenFormatNotImplementedError("Tailwind v4 @theme", "parser");
+}

package/dist/cloudflare/core/tokens/parsers/tokens-studio.js

@@ -0,0 +1,4 @@
+import { TokenFormatNotImplementedError } from "./stubs.js";
+export function parseTokensStudio(_input) {
+    throw new TokenFormatNotImplementedError("Tokens Studio", "parser");
+}

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

@@ -0,0 +1,148 @@
+/**
+ * Zod schemas for the figma_export_tokens and figma_import_tokens MCP tools.
+ *
+ * Kept in a dedicated file because they're the AI-facing surface of the token
+ * sync engine — the descriptions matter for prompt comprehension, and they
+ * need to stay in sync with `src/core/tokens/types.ts` (the internal model).
+ */
+import { z } from "zod";
+/**
+ * Output format enum mirrors `ExportFormat` from `./types.ts`. Listed in the
+ * same priority order — DTCG and Tokens Studio first as the canonical JSON
+ * outputs, then CSS-family formats, then code modules, then back-compat.
+ */
+export const ExportFormatSchema = z.enum([
+    "dtcg",
+    "tokens-studio",
+    "css-vars",
+    "tailwind-v4",
+    "tailwind-v3",
+    "scss",
+    "less",
+    "ts-module",
+    "json-flat",
+    "json-nested",
+    "style-dictionary-v3",
+]);
+export const ImportFormatSchema = z.enum([
+    "auto",
+    "dtcg",
+    "tokens-studio",
+    "css-vars",
+    "tailwind-v4",
+    "tailwind-v3-config",
+    "scss",
+    "style-dictionary-v3",
+    "json-flat",
+    "json-nested",
+]);
+export const SyncStrategySchema = z.enum(["merge", "replace", "dry-run"]);
+export const ConflictResolutionSchema = z.enum([
+    "ask",
+    "figma-wins",
+    "code-wins",
+    "skip",
+]);
+const ColorFormatSchema = z.enum(["hex", "hex8", "rgba", "oklch", "hsl"]);
+const SizeUnitSchema = z.enum(["px", "rem", "pt", "dp"]);
+/**
+ * Schema for figma_export_tokens. Most fields are optional — the typical call
+ * is zero-arg, picking everything up from `tokens.config.json` autodiscovery.
+ */
+export const ExportTokensInputSchema = z.object({
+    scope: z
+        .enum(["file", "collection"])
+        .optional()
+        .describe("Whether to export the entire file's variables ('file', default) or just specific collections via collectionIds."),
+    collectionIds: z
+        .array(z.string())
+        .optional()
+        .describe("Specific Figma collection IDs to export. Required when scope is 'collection'. Use figma_get_variables to enumerate available collections."),
+    modes: z
+        .union([z.array(z.string()), z.literal("all")])
+        .optional()
+        .describe("Modes to include in the output. 'all' (default) exports every mode in every collection. Pass an array like ['Light', 'Dark'] to filter."),
+    format: ExportFormatSchema.optional().describe("Specific output format to emit. When omitted, formats come from tokens.config.json's generated.formats list. Common starting choices: 'dtcg' for the canonical JSON, 'css-vars' for runtime CSS custom properties, 'tailwind-v4' for Tailwind v4 @theme blocks."),
+    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)."),
+    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."),
+    prefix: z
+        .string()
+        .optional()
+        .describe("Prefix prepended to every output token name (e.g. 'ds-', 'al-'). Only affects formatters that emit named tokens — DTCG and JSON outputs use unmodified paths."),
+    resolveAliases: z
+        .boolean()
+        .optional()
+        .describe("If true, alias references are resolved to literal values in the output. Default is false for JSON formats (preserves alias semantics) and true for CSS/SCSS/Tailwind/etc. (which can't natively express aliases)."),
+    splitByMode: z
+        .boolean()
+        .optional()
+        .describe("Emit one file per mode (e.g. tokens-light.css, tokens-dark.css). Default false (single file with all modes)."),
+    splitByCollection: z
+        .boolean()
+        .optional()
+        .describe("Emit one file per Figma collection. Default false. Useful when collections map to different runtime themes."),
+    colorFormat: ColorFormatSchema.optional().describe("Color value format in the output. Default: 'hex'. Use 'oklch' for modern Tailwind v4 charts."),
+    sizeUnit: SizeUnitSchema.optional().describe("Unit for dimension tokens. Default: 'rem' for web outputs, 'pt' for iOS, 'dp' for Android."),
+    remBase: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Base font size in pixels for px→rem conversion. Default: 16."),
+});
+/**
+ * Schema for figma_import_tokens. Mirrors export's shape on the inverse
+ * direction: instead of producing files, this consumes payloads or files and
+ * pushes the diff to Figma.
+ */
+export const ImportTokensInputSchema = z
+    .object({
+    format: ImportFormatSchema.optional().describe("Format of the input payload. 'auto' (default) detects from payload shape or file extension. Pass an explicit format if auto-detection misfires."),
+    payload: z
+        .string()
+        .optional()
+        .describe("Single-file content to import. Use this for one-shot imports without setting up tokens.config.json. Mutually exclusive with `files` and `configPath`."),
+    files: z
+        .array(z.object({
+        path: z.string().describe("Relative or absolute filesystem path."),
+        content: z.string().describe("File contents."),
+    }))
+        .optional()
+        .describe("Multi-file import (used for Tokens Studio's split-set format, or for projects with many DTCG source files). Mutually exclusive with `payload` and `configPath`."),
+    configPath: z
+        .string()
+        .optional()
+        .describe("Explicit path to tokens.config.json. When omitted, the tool autodiscovers and uses the config's source.dir to find files. Mutually exclusive with `payload` and `files`."),
+    strategy: SyncStrategySchema.optional().describe("How to apply changes. 'merge' (default) diffs against current Figma state and applies only deltas, preserving Figma-only variables. 'replace' wipes the target collections and rewrites. 'dry-run' computes the diff and reports without touching Figma."),
+    collectionMapping: z
+        .record(z.string())
+        .optional()
+        .describe("Map input token set names to Figma collection names. Example: {'primitives': 'Primitive Tokens'}. When omitted, set names map 1:1 to collection names."),
+    modeMapping: z
+        .record(z.string())
+        .optional()
+        .describe("Map input mode names to Figma mode names. Useful when source uses 'light'/'dark' and Figma uses 'Light'/'Dark'. Defaults to 1:1 mapping with case preservation."),
+    prefix: z
+        .string()
+        .optional()
+        .describe("Prefix to strip from input token names on import. E.g. with prefix 'ds-', a token named '--ds-color-primary' becomes 'color/primary'."),
+    onConflict: ConflictResolutionSchema.optional().describe("How to resolve true two-sided conflicts (both Figma and code changed the same token since last sync). 'ask' (default) surfaces the conflict and writes nothing. 'figma-wins' / 'code-wins' apply the corresponding side. 'skip' leaves conflicted tokens alone but proceeds with the rest."),
+    dryRun: z
+        .boolean()
+        .optional()
+        .describe("Shorthand for strategy: 'dry-run'. Computes the diff and returns a preview without applying any changes to Figma."),
+})
+    .refine((data) => {
+    // Exactly one of payload / files / configPath should be set (or none,
+    // which triggers tokens.config.json autodiscovery).
+    const sources = [data.payload, data.files, data.configPath].filter((x) => x !== undefined);
+    return sources.length <= 1;
+}, {
+    message: "Pass at most one of: payload, files, configPath. (Or none, to autodiscover tokens.config.json.)",
+});