@mp3wizard/figma-console-mcp 1.23.1 → 1.27.2

package/dist/core/tokens/config.js

@@ -0,0 +1,285 @@
+/**
+ * tokens.config.json schema, loader, and autodiscovery for the figma-console-mcp
+ * token sync engine.
+ *
+ * Both figma_export_tokens and figma_import_tokens read this single config so
+ * follow-up calls in a project are zero-arg. Autodiscovery walks up from the
+ * current working directory looking for `tokens.config.json` at each level
+ * — same convention as `tsconfig.json`, `package.json`, `.eslintrc`, etc.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+/**
+ * Schema for a single output target in `tokens.config.json`. Each entry
+ * produces one or more files when figma_export_tokens runs.
+ */
+const OutputTargetSchema = z.object({
+    format: z.enum([
+        "dtcg",
+        "tokens-studio",
+        "css-vars",
+        "tailwind-v4",
+        "tailwind-v3",
+        "scss",
+        "less",
+        "ts-module",
+        "json-flat",
+        "json-nested",
+        "style-dictionary-v3",
+    ]),
+    /** Optional filename override. Default is derived from format + scope. */
+    filename: z.string().optional(),
+    /** Output prefix applied to every token name (e.g. "ds-", "al-"). */
+    prefix: z.string().optional(),
+    /** Emit one file per mode (e.g. tokens-light.css, tokens-dark.css). */
+    splitByMode: z.boolean().optional(),
+    /** Emit one file per token set / Figma collection. */
+    splitByCollection: z.boolean().optional(),
+    /**
+     * If true, alias references are resolved to literal values in the output.
+     * If false, aliases are preserved (default for JSON formats, forced true
+     * for CSS/SCSS/Tailwind/etc. since they can't natively express aliases).
+     */
+    resolveAliases: z.boolean().optional(),
+    /** Per-target transform options. Override the global defaults. */
+    transforms: z
+        .object({
+        colorFormat: z.enum(["hex", "hex8", "rgba", "oklch", "hsl"]).optional(),
+        sizeUnit: z.enum(["px", "rem", "pt", "dp"]).optional(),
+        remBase: z.number().positive().optional(),
+    })
+        .optional(),
+});
+/**
+ * Full schema for `tokens.config.json`. Every field is optional so the
+ * minimum-viable config is `{ "figmaFile": "..." }` — the rest gets sensible
+ * defaults.
+ */
+export const TokensConfigSchema = z
+    .object({
+    /** Optional JSON Schema URL for editor autocompletion. */
+    $schema: z.string().optional(),
+    /**
+     * Figma file URL or fileKey. When omitted, tools fall back to the
+     * currently-connected Desktop Bridge plugin's file (Local Mode) or the
+     * file context bound by figma_pair_plugin (Cloud Mode).
+     */
+    figmaFile: z.string().optional(),
+    /** Where the canonical (committed) token sources live. */
+    source: z
+        .object({
+        /** Directory holding the canonical token files. */
+        dir: z.string(),
+        /** Glob pattern within dir. Default: "*.tokens.json" */
+        pattern: z.string().optional(),
+        /**
+         * Canonical format for source files. DTCG is the recommended default;
+         * Tokens Studio is supported for users who already have a `$themes.json`
+         * setup (e.g. Altitude).
+         */
+        canonical: z.enum(["dtcg", "tokens-studio"]).default("dtcg"),
+    })
+        .default({ dir: "src/styles/tokens", canonical: "dtcg" }),
+    /** Where build outputs (CSS, Tailwind, etc.) get written. */
+    generated: z
+        .object({
+        dir: z.string().default("src/styles/generated"),
+        formats: z.array(OutputTargetSchema).default([]),
+    })
+        .optional(),
+    /** Mode name mappings (Figma mode name → output mode name). */
+    modes: z
+        .object({
+        /** e.g. { "Light": "light", "Dark": "dark" } */
+        map: z.record(z.string()).optional(),
+        /** Default mode if a token has no explicit mode (e.g. "Light"). */
+        default: z.string().optional(),
+    })
+        .optional(),
+    /** Default conflict-resolution strategy when not specified per-call. */
+    conflictResolution: z
+        .enum(["ask", "figma-wins", "code-wins", "skip"])
+        .default("ask"),
+    /** Behavior for tokens that exist on one side but not the other. */
+    sync: z
+        .object({
+        onMissingInCode: z
+            .enum(["preserve", "delete", "warn"])
+            .default("preserve"),
+        onMissingInFigma: z
+            .enum(["preserve", "delete", "warn"])
+            .default("preserve"),
+    })
+        .optional(),
+})
+    .strict();
+/**
+ * Walk up from `startDir` looking for `tokens.config.json`. Returns the first
+ * match, or `null` if none found by the filesystem root.
+ */
+export function findTokensConfig(startDir) {
+    let dir = resolve(startDir);
+    // Hard cap on directory traversal so a misconfigured startDir can't loop
+    // forever (defense against symlinks/weird filesystems).
+    const maxDepth = 32;
+    for (let i = 0; i < maxDepth; i++) {
+        const candidate = join(dir, "tokens.config.json");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            // Hit filesystem root, no config found.
+            return null;
+        }
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Load and validate `tokens.config.json`. If `explicitPath` is provided, uses
+ * that; otherwise autodiscovers by walking up from `cwd` (default
+ * `process.cwd()`).
+ *
+ * Returns `null` if no config is found AND no explicit path was given. Throws
+ * if an explicit path doesn't exist, or if the discovered file fails schema
+ * validation.
+ */
+export function loadTokensConfig(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const configPath = opts.explicitPath
+        ? resolve(opts.explicitPath)
+        : findTokensConfig(cwd);
+    if (!configPath)
+        return null;
+    if (!existsSync(configPath)) {
+        throw new Error(`[figma-console-mcp] tokens.config.json not found at ${configPath}`);
+    }
+    const raw = readFileSync(configPath, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`[figma-console-mcp] tokens.config.json at ${configPath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const result = TokensConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  • ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        throw new Error(`[figma-console-mcp] tokens.config.json at ${configPath} failed validation:\n${issues}`);
+    }
+    return {
+        config: result.data,
+        configPath,
+        projectRoot: dirname(configPath),
+    };
+}
+/**
+ * Default config used when none is found. Drives the "no-config detected"
+ * response shape from figma_export_tokens — the AI uses this to propose a
+ * scaffold to the user.
+ */
+export const DEFAULT_TOKENS_CONFIG = {
+    source: { dir: "src/styles/tokens", canonical: "dtcg" },
+    generated: {
+        dir: "src/styles/generated",
+        formats: [
+            { format: "css-vars", splitByMode: true },
+        ],
+    },
+    conflictResolution: "ask",
+};
+/**
+ * Build a `suggestedScaffold` payload returned when a tool is called and no
+ * `tokens.config.json` exists. The AI presents this scaffold to the user,
+ * writes the files via its native edit/write tools, then calls the original
+ * tool again.
+ */
+export function buildSuggestedScaffold(opts) {
+    const config = {
+        $schema: "https://figma-console-mcp.southleft.com/schemas/tokens.config.v1.json",
+        source: { dir: "src/styles/tokens", canonical: "dtcg" },
+        generated: {
+            dir: "src/styles/generated",
+            formats: pickStartingFormats(opts.detectedFramework),
+        },
+        conflictResolution: "ask",
+    };
+    const stylesheetImport = pickStylesheetImport(opts.detectedFramework);
+    return {
+        configContent: JSON.stringify(config, null, 2),
+        directories: [config.source.dir, config.generated?.dir ?? "src/styles/generated"],
+        stylesheetImport,
+        nextSteps: [
+            "1. Write `tokens.config.json` at the project root using `configContent`.",
+            `2. Create the directories: ${config.source.dir} and ${config.generated?.dir}.`,
+            `3. Add this line to your main stylesheet:\n     ${stylesheetImport}`,
+            "4. Run `figma_export_tokens` again — it'll pick up the new config and populate the source dir.",
+        ].join("\n"),
+    };
+}
+function pickStartingFormats(framework) {
+    // Always emit DTCG as the canonical committed source; layer the
+    // framework-appropriate runtime format on top.
+    const base = [];
+    switch (framework) {
+        case "tailwind-v4":
+            base.push({ format: "tailwind-v4", splitByMode: true });
+            break;
+        case "tailwind-v3":
+            base.push({ format: "tailwind-v3" });
+            break;
+        case "scss":
+            base.push({ format: "scss", splitByMode: true });
+            break;
+        case "ts":
+            base.push({ format: "ts-module" });
+            base.push({ format: "css-vars", splitByMode: true });
+            break;
+        case "css":
+        default:
+            base.push({ format: "css-vars", splitByMode: true });
+            break;
+    }
+    return base;
+}
+function pickStylesheetImport(framework) {
+    switch (framework) {
+        case "tailwind-v4":
+            return "@import './styles/generated/tailwind.theme.css';";
+        case "scss":
+            return "@use './styles/generated/tokens.scss' as *;";
+        case "ts":
+        case "css":
+        default:
+            return "@import './styles/generated/tokens.css';";
+    }
+}
+/**
+ * Pick the export formats from a loaded config that map to a given runtime
+ * format. Used by figma_export_tokens to decide which generated files to
+ * write. Returns the list verbatim if the caller passed an explicit format.
+ */
+export function resolveOutputTargets(config, explicitFormat) {
+    if (explicitFormat) {
+        // Caller specified a format directly; ignore config's generated list.
+        return [{ format: explicitFormat }];
+    }
+    if (!config?.generated?.formats?.length) {
+        // No formats configured. Default to DTCG only — produces the canonical
+        // source files but no derived runtime outputs.
+        return [{ format: "dtcg" }];
+    }
+    return config.generated.formats;
+}
+/**
+ * Resolve the conflict-resolution strategy. Per-call argument wins over config
+ * default, which wins over the global default ("ask").
+ */
+export function resolveConflictStrategy(config, perCall) {
+    return perCall ?? config?.conflictResolution ?? "ask";
+}
+//# sourceMappingURL=config.js.map

package/dist/core/tokens/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/tokens/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;GAGG;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC;QACb,MAAM;QACN,eAAe;QACf,UAAU;QACV,aAAa;QACb,aAAa;QACb,MAAM;QACN,MAAM;QACN,WAAW;QACX,WAAW;QACX,aAAa;QACb,qBAAqB;KACb,CAAC;IACX,0EAA0E;IAC1E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,qEAAqE;IACrE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,uEAAuE;IACvE,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACnC,sDAAsD;IACtD,iBAAiB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACzC;;;;OAIG;IACH,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACtC,kEAAkE;IAClE,UAAU,EAAE,CAAC;SACV,MAAM,CAAC;QACN,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE;QACvE,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE;QACtD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;KAC1C,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,0DAA0D;IAC1D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B;;;;OAIG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,0DAA0D;IAC1D,MAAM,EAAE,CAAC;SACN,MAAM,CAAC;QACN,mDAAmD;QACnD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;QACf,wDAAwD;QACxD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC9B;;;;WAIG;QACH,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;KAC7D,CAAC;SACD,OAAO,CAAC,EAAE,GAAG,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAC3D,6DAA6D;IAC7D,SAAS,EAAE,CAAC;SACT,MAAM,CAAC;QACN,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,sBAAsB,CAAC;QAC/C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;KACjD,CAAC;SACD,QAAQ,EAAE;IACb,+DAA+D;IAC/D,KAAK,EAAE,CAAC;SACL,MAAM,CAAC;QACN,gDAAgD;QAChD,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;QACpC,mEAAmE;QACnE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC;SACD,QAAQ,EAAE;IACb,wEAAwE;IACxE,kBAAkB,EAAE,CAAC;SAClB,IAAI,CAAC,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;SAChD,OAAO,CAAC,KAAK,CAAC;IACjB,oEAAoE;IACpE,IAAI,EAAE,CAAC;SACJ,MAAM,CAAC;QACN,eAAe,EAAE,CAAC;aACf,IAAI,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;aACpC,OAAO,CAAC,UAAU,CAAC;QACtB,gBAAgB,EAAE,CAAC;aAChB,IAAI,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;aACpC,OAAO,CAAC,UAAU,CAAC;KACvB,CAAC;SACD,QAAQ,EAAE;CACd,CAAC;KACD,MAAM,EAAE,CAAC;AAgBZ;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,IAAI,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,yEAAyE;IACzE,wDAAwD;IACxD,MAAM,QAAQ,GAAG,EAAE,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;QAClD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACnB,wCAAwC;YACxC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAG7B,EAAE;IACJ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACtC,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY;QAClC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC;QAC5B,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAE1B,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,uDAAuD,UAAU,EAAE,CACpE,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,6CAA6C,UAAU,uBACrD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACnD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CACb,6CAA6C,UAAU,wBAAwB,MAAM,EAAE,CACxF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,UAAU;QACV,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC;KACjC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,MAAM,EAAE,EAAE,GAAG,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,EAAE;IACvD,SAAS,EAAE;QACT,GAAG,EAAE,sBAAsB;QAC3B,OAAO,EAAE;YACP,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE;SAC1C;KACF;IACD,kBAAkB,EAAE,KAAK;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAGtC;IAMC,MAAM,MAAM,GAAiB;QAC3B,OAAO,EACL,uEAAuE;QACzE,MAAM,EAAE,EAAE,GAAG,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,EAAE;QACvD,SAAS,EAAE;YACT,GAAG,EAAE,sBAAsB;YAC3B,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,iBAAiB,CAAC;SACrD;QACD,kBAAkB,EAAE,KAAK;KAC1B,CAAC;IAEF,MAAM,gBAAgB,GAAG,oBAAoB,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAEtE,OAAO;QACL,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,EAAE,GAAG,IAAI,sBAAsB,CAAC;QACjF,gBAAgB;QAChB,SAAS,EAAE;YACT,0EAA0E;YAC1E,8BAA8B,MAAM,CAAC,MAAM,CAAC,GAAG,QAAQ,MAAM,CAAC,SAAS,EAAE,GAAG,GAAG;YAC/E,mDAAmD,gBAAgB,EAAE;YACrE,gGAAgG;SACjG,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAC1B,SAAiE;IAEjE,gEAAgE;IAChE,+CAA+C;IAC/C,MAAM,IAAI,GAAmB,EAAE,CAAC;IAChC,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,aAAa;YAChB,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;YACxD,MAAM;QACR,KAAK,aAAa;YAChB,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;YACrC,MAAM;QACR,KAAK,MAAM;YACT,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;YACjD,MAAM;QACR,KAAK,IAAI;YACP,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;YACnC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,MAAM;QACR,KAAK,KAAK,CAAC;QACX;YACE,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,MAAM;IACV,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,oBAAoB,CAC3B,SAAiE;IAEjE,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,aAAa;YAChB,OAAO,kDAAkD,CAAC;QAC5D,KAAK,MAAM;YACT,OAAO,6CAA6C,CAAC;QACvD,KAAK,IAAI,CAAC;QACV,KAAK,KAAK,CAAC;QACX;YACE,OAAO,0CAA0C,CAAC;IACtD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAA2B,EAC3B,cAAwC;IAExC,IAAI,cAAc,EAAE,CAAC;QACnB,sEAAsE;QACtE,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACxC,uEAAuE;QACvE,+CAA+C;QAC/C,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAA2B,EAC3B,OAAuC;IAEvC,OAAO,OAAO,IAAI,MAAM,EAAE,kBAAkB,IAAI,KAAK,CAAC;AACxD,CAAC"}

package/dist/core/tokens/figma-converter.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Convert Figma's variables API response into our canonical TokenDocument.
+ *
+ * Input: the shape produced by `formatVariables()` in src/core/figma-api.ts
+ * (an object with `collections` and `variables` arrays, matching either the
+ * REST API's response or the Desktop Bridge plugin's `getLocalVariablesAsync`
+ * normalized payload).
+ *
+ * Output: a TokenDocument with one TokenSet per collection, paths derived
+ * from Figma variable names (slash-separated → path arrays), values
+ * normalized to our TokenValue shape, and Figma IDs preserved in
+ * $extensions["figma-console-mcp"] for round-trip non-destructiveness.
+ */
+import type { TokenDocument } from "./types.js";
+/**
+ * Shape of Figma's variable collection as returned by formatVariables(). We
+ * use a narrow structural type rather than importing the existing `any`
+ * shape from figma-api.ts.
+ */
+interface FigmaCollection {
+    id: string;
+    name: string;
+    key?: string;
+    modes: Array<{
+        modeId: string;
+        name: string;
+    }>;
+    variableIds: string[];
+}
+interface FigmaVariable {
+    id: string;
+    name: string;
+    key?: string;
+    resolvedType: "COLOR" | "FLOAT" | "STRING" | "BOOLEAN";
+    variableCollectionId: string;
+    description?: string;
+    scopes?: string[];
+    /**
+     * Per-mode values. Each value is either a literal or a `{ type: "VARIABLE_ALIAS", id }`
+     * pointing at another variable.
+     */
+    valuesByMode: Record<string, FigmaValue>;
+}
+type FigmaValue = {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+} | number | string | boolean | VariableAlias;
+interface VariableAlias {
+    type: "VARIABLE_ALIAS";
+    id: string;
+}
+export interface FigmaVariablesPayload {
+    collections: FigmaCollection[];
+    variables: FigmaVariable[];
+}
+export interface ConvertOptions {
+    /** Figma file key. Stored in document metadata. */
+    figmaFileKey?: string;
+    /** ISO timestamp to stamp the exportedAt field. Defaults to now. */
+    exportedAt?: string;
+    /** MCP version string. */
+    mcpVersion?: string;
+    /** Filter to specific collection IDs. Undefined or empty means all. */
+    collectionIds?: string[];
+    /** Filter to specific mode names. Undefined means all. */
+    modes?: string[] | "all";
+    /** Optional prefix that gets stripped from variable names on conversion. */
+    stripPrefix?: string;
+}
+export interface ConvertResult {
+    document: TokenDocument;
+    warnings: string[];
+}
+/**
+ * Convert a Figma variables payload to our canonical TokenDocument.
+ */
+export declare function convertFigmaVariablesToDocument(payload: FigmaVariablesPayload, opts?: ConvertOptions): ConvertResult;
+export {};
+//# sourceMappingURL=figma-converter.d.ts.map

package/dist/core/tokens/figma-converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-converter.d.ts","sourceRoot":"","sources":["../../../src/core/tokens/figma-converter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAEV,aAAa,EAId,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,UAAU,eAAe;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC1C;AAED,KAAK,UAAU,GACX;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,MAAM,GACN,MAAM,GACN,OAAO,GACP,aAAa,CAAC;AAElB,UAAU,aAAa;IACrB,IAAI,EAAE,gBAAgB,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACzB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,qBAAqB,EAC9B,IAAI,GAAE,cAAmB,GACxB,aAAa,CA6Bf"}

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

@@ -0,0 +1,196 @@
+/**
+ * Convert Figma's variables API response into our canonical TokenDocument.
+ *
+ * Input: the shape produced by `formatVariables()` in src/core/figma-api.ts
+ * (an object with `collections` and `variables` arrays, matching either the
+ * REST API's response or the Desktop Bridge plugin's `getLocalVariablesAsync`
+ * normalized payload).
+ *
+ * Output: a TokenDocument with one TokenSet per collection, paths derived
+ * from Figma variable names (slash-separated → path arrays), values
+ * normalized to our TokenValue shape, and Figma IDs preserved in
+ * $extensions["figma-console-mcp"] for round-trip non-destructiveness.
+ */
+/**
+ * Convert a Figma variables payload to our canonical TokenDocument.
+ */
+export function convertFigmaVariablesToDocument(payload, opts = {}) {
+    const warnings = [];
+    // Build a variable index for alias resolution: variableId → variable
+    const variableById = new Map();
+    for (const v of payload.variables)
+        variableById.set(v.id, v);
+    // 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));
+    return {
+        document: {
+            $schema: "https://figma-console-mcp.southleft.com/schemas/dtcg-extended-v1.json",
+            sets,
+            meta: {
+                figmaFileKey: opts.figmaFileKey,
+                exportedAt: opts.exportedAt ?? new Date().toISOString(),
+                mcpVersion: opts.mcpVersion,
+            },
+        },
+        warnings,
+    };
+}
+function convertCollection(collection, allVariables, variableById, opts, warnings) {
+    // Mode filter: keep only modes the caller wants, intersected with what
+    // the collection actually has.
+    const wantedModes = !opts.modes || opts.modes === "all"
+        ? collection.modes
+        : 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));
+    return {
+        name: collection.name,
+        modes: wantedModes.map((m) => m.name),
+        tokens,
+        meta: {
+            figmaCollectionId: collection.id,
+        },
+    };
+}
+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"].
+    let name = variable.name;
+    if (opts.stripPrefix && name.startsWith(opts.stripPrefix)) {
+        name = name.slice(opts.stripPrefix.length);
+    }
+    const path = name.split("/").filter(Boolean);
+    // 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.
+    const values = {};
+    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);
+    }
+    return {
+        path,
+        type,
+        description: variable.description || undefined,
+        values,
+        extensions: {
+            "figma-console-mcp": {
+                variableId: variable.id,
+                collectionId: variable.variableCollectionId,
+                lastSyncedAt: new Date().toISOString(),
+                // We snapshot the synced value so future merge calls can detect
+                // two-sided conflicts.
+                lastSyncedValue: { ...values },
+            },
+        },
+    };
+}
+function mapResolvedType(resolvedType, variableName, warnings) {
+    switch (resolvedType) {
+        case "COLOR":
+            return "color";
+        case "FLOAT":
+            // Figma FLOAT covers both pure numbers and dimensions. We default to
+            // "dimension" because the typical FLOAT variable represents spacing,
+            // sizing, or radius — all dimensions. A future enhancement could
+            // sniff the variable name (e.g. "opacity/*" → "number") for better
+            // type fidelity.
+            return inferFloatType(variableName);
+        case "STRING":
+            return inferStringType(variableName);
+        case "BOOLEAN":
+            return "boolean";
+        default: {
+            const _exhaustive = resolvedType;
+            warnings.push(`Unknown resolvedType "${_exhaustive}" for variable "${variableName}"; treating as string.`);
+            return "string";
+        }
+    }
+}
+function inferFloatType(variableName) {
+    const lower = variableName.toLowerCase();
+    if (lower.includes("opacity") || lower.includes("alpha"))
+        return "number";
+    if (lower.includes("font-weight") || lower.includes("weight"))
+        return "fontWeight";
+    if (lower.includes("duration") || lower.includes("delay"))
+        return "duration";
+    // Default: treat numeric variables as dimensions (px values).
+    return "dimension";
+}
+function inferStringType(variableName) {
+    const lower = variableName.toLowerCase();
+    if (lower.includes("font-family") || lower.includes("font/family"))
+        return "fontFamily";
+    return "string";
+}
+function convertValue(rawValue, resolvedType, variableById, warnings) {
+    // Alias references: convert variable ID → path-based reference for DTCG.
+    if (isVariableAlias(rawValue)) {
+        const target = variableById.get(rawValue.id);
+        if (!target) {
+            // Cross-library alias — target is in a published library this file
+            // consumes, not in the local variable set. Preserve the original
+            // Figma variable ID in the reference syntax so round-trip can
+            // recover it AND formatters can detect this is unresolvable (vs a
+            // genuine local-path alias).
+            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}}` };
+    }
+    // Literal values per type.
+    if (resolvedType === "COLOR") {
+        if (typeof rawValue === "object" && rawValue !== null && "r" in rawValue) {
+            return { literal: rgbaToHex(rawValue) };
+        }
+        warnings.push(`COLOR value isn't an RGB object: ${JSON.stringify(rawValue)}`);
+        return { literal: String(rawValue) };
+    }
+    if (resolvedType === "FLOAT") {
+        return { literal: typeof rawValue === "number" ? rawValue : Number(rawValue) };
+    }
+    if (resolvedType === "BOOLEAN") {
+        return { literal: Boolean(rawValue) };
+    }
+    // STRING and fallthrough.
+    return { literal: typeof rawValue === "string" ? rawValue : String(rawValue) };
+}
+function isVariableAlias(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "type" in value &&
+        value.type === "VARIABLE_ALIAS");
+}
+/**
+ * Convert Figma's `{r, g, b, a}` floats (0–1 range) to a hex string. Returns
+ * `#RRGGBB` when alpha is 1 (or absent), `#RRGGBBAA` when alpha < 1.
+ */
+function rgbaToHex(rgba) {
+    const r = clampByte(rgba.r);
+    const g = clampByte(rgba.g);
+    const b = clampByte(rgba.b);
+    const a = rgba.a ?? 1;
+    const hex = `#${byteToHex(r)}${byteToHex(g)}${byteToHex(b)}`;
+    if (a >= 1)
+        return hex;
+    return `${hex}${byteToHex(clampByte(a))}`;
+}
+function clampByte(f) {
+    return Math.max(0, Math.min(255, Math.round(f * 255)));
+}
+function byteToHex(byte) {
+    return byte.toString(16).padStart(2, "0").toUpperCase();
+}
+//# sourceMappingURL=figma-converter.js.map

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

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

package/dist/core/tokens/formatters/css-vars.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+import type { TokenDocument } from "../types.js";
+import type { FormatOptions, FormatResult } from "./index.js";
+export declare function formatCssVars(doc: TokenDocument, opts: FormatOptions): FormatResult;
+//# sourceMappingURL=css-vars.d.ts.map

package/dist/core/tokens/formatters/css-vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-vars.d.ts","sourceRoot":"","sources":["../../../../src/core/tokens/formatters/css-vars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAS,aAAa,EAAwB,MAAM,aAAa,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D,wBAAgB,aAAa,CAC3B,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,aAAa,GAClB,YAAY,CA0Dd"}