figma-console-mcp 1.26.0 → 1.27.0

package/README.md

@@ -51,9 +51,9 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 | Real-time monitoring (console, selection) | ✅ | ❌ | ❌ |
 | Desktop Bridge plugin | ✅ | ✅ | ❌ |
 | Requires Node.js | Yes | **No** | No |
-| **Total tools available** | **101** | **93** | **9** |
+| **Total tools available** | **103** | **93** | **9** |
 
-> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 101 tools with real-time monitoring.
+> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 103 tools with real-time monitoring.
 
 ---
 
@@ -61,7 +61,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 **Best for:** Designers who want full AI-assisted design capabilities.
 
-**What you get:** All 101 tools including design creation, variable management, and component instantiation.
+**What you get:** All 103 tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -128,9 +128,11 @@ If you're not sure where to put the JSON configuration above, here's where each
 3. Select `~/.figma-console-mcp/plugin/manifest.json` (stable path, auto-created by the MCP server)
 4. Run the plugin in your Figma file — it scans ports 9223–9232 and connects automatically to your running MCP server
 
-> **Heads-up on plugin updates.** Figma caches plugin files (`code.js` and `ui.html`) at the application level. When the MCP server publishes a plugin update — typically a `npm update` / new `npx` cache pull — re-import the manifest at `~/.figma-console-mcp/plugin/manifest.json` (Plugins → Manage plugins → re-import) to refresh the cached code. The stable path never changes, so re-importing is a quick one-click step.
+> **Heads-up on plugin updates.** Figma caches plugin files (`code.js` and `ui.html`) at the application level. The MCP server refreshes the files at `~/.figma-console-mcp/plugin/` on every startup, but Figma keeps using its cached copy until you re-import the manifest.
 >
-> The MCP server refreshes the files at the stable path on every startup; re-importing in Figma is what makes Figma pick them up.
+> **Re-importing is _required_ only when a release notes entry says so** — typically when the plugin adds a new method the server needs (e.g. v1.22.4, v1.10.0). For most upgrades the new server stays wire-compatible with the previous plugin, and re-importing is **optional**: you'll still get every functional change, just not the cosmetic plugin-side touches (status-pill copy, `pluginVersion` reporting).
+>
+> When you do re-import: Plugins → Manage plugins → re-import `~/.figma-console-mcp/plugin/manifest.json`. The stable path never changes, so it's a one-click step.
 
 #### Step 4: Restart Your MCP Client
 
@@ -156,7 +158,7 @@ Create a simple frame with a blue background
 
 **Best for:** Developers who want to modify source code or contribute to the project.
 
-**What you get:** Same 101 tools as NPX, plus full source code access.
+**What you get:** Same 103 tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -245,7 +247,7 @@ Ready for design creation? Follow the [NPX Setup](#-npx-setup-recommended) guide
 
 **Best for:** Using Claude.ai, v0, Replit, or Lovable to create and modify Figma designs — no Node.js required.
 
-**What you get:** 93 tools including full write access — design creation, variable management, component instantiation, and all REST API tools. Only real-time monitoring (console logs, selection tracking, document changes) requires Local Mode.
+**What you get:** 95 tools including full write access — design creation, variable management, component instantiation, and all REST API tools. Only real-time monitoring (console logs, selection tracking, document changes) requires Local Mode.
 
 #### Prerequisites
 
@@ -302,7 +304,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | Feature | NPX (Recommended) | Cloud Mode | Local Git | Remote SSE |
 |---------|-------------------|------------|-----------|------------|
 | **Setup time** | ~10 minutes | ~5 minutes | ~15 minutes | ~2 minutes |
-| **Total tools** | **101** | **93** | **101** | **9** (read-only) |
+| **Total tools** | **103** | **93** | **103** | **9** (read-only) |
 | **Design creation** | ✅ | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
@@ -317,7 +319,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | **Automatic updates** | ✅ (`@latest`) | ✅ | Manual (`git pull`) | ✅ |
 | **Source code access** | ❌ | ❌ | ✅ | ❌ |
 
-> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 101 tools.
+> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 103 tools.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -419,6 +421,10 @@ When you first use design system tools:
 - `figma_check_design_parity` - Compare Figma component specs against code implementation, producing a scored diff report with actionable fix items
 - `figma_generate_component_doc` - Generate platform-agnostic markdown documentation by merging Figma design data with code-side info
 
+### 🔁 Token Sync (Local Mode + Cloud Mode)
+- `figma_export_tokens` - **Export Figma variables to design token files in your codebase.** Canonical DTCG JSON + CSS custom properties out of the box. Diff-aware merge against existing source files (only writes what changed). `tokens.config.json` autodiscovery means zero-arg calls after first setup. Replaces Style Dictionary and Tokens Studio's export pipeline for popular styling methods.
+- `figma_import_tokens` - **Push code-side token edits back to Figma.** Diff against current Figma state, apply only the deltas. Round-trip safe — Figma variable IDs preserved in DTCG `$extensions["figma-console-mcp"]` so renames on either side don't create duplicates. Dry-run default for safety. In Cloud Mode, pass tokens inline via `payload` or `files` (no local filesystem access).
+
 ### 🔧 Variable Management (Local Mode + Cloud Mode)
 - `figma_create_variable_collection` - Create new variable collections with modes
 - `figma_create_variable` - Create COLOR, FLOAT, STRING, or BOOLEAN variables
@@ -653,7 +659,7 @@ The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to t
 - The MCP server communicates via **WebSocket** through the Desktop Bridge plugin
 - The server tries port 9223 first, then automatically falls back through ports 9224–9232 if needed
 - The plugin scans all ports in the range and connects to every active server it finds
-- All 101 tools work through the WebSocket transport
+- All 103 tools work through the WebSocket transport
 
 **Multiple files:** The WebSocket server supports multiple simultaneous plugin connections — one per open Figma file. Each connection is tracked by file key with independent state (selection, document changes, console logs).
 
@@ -792,7 +798,7 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.23.0 (Stable) - Production-ready with version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 101 tools, Comments API, and MCP Apps
+**Current Status:** v1.23.0 (Stable) - Production-ready with version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 103 tools, Comments API, and MCP Apps
 
 **Recent Releases:**
 - [x] **v1.17.0** - Figma Slides Support: 15 new tools for managing presentations — slides, transitions, content, reordering, and navigation. Inspired by Toni Haidamous (PR #11).

package/dist/core/tokens/alias-resolver.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Alias reference resolution and validation.
+ *
+ * DTCG alias references look like `{color.primary}` or `{tier-1.color.blue.500}`.
+ * They can chain (an alias can reference another alias), but cycles are an
+ * error.
+ *
+ * This module:
+ *   - Resolves an alias to its eventual literal value (for formatters that
+ *     can't natively express references — CSS, SCSS, Tailwind).
+ *   - Validates that every alias points to an existing token.
+ *   - Detects cycles.
+ */
+import type { Token, TokenDocument, TokenValue } from "./types.js";
+/**
+ * Build a lookup map from dot-path strings (e.g. "color.primary") to Token
+ * objects. Used as the index for resolveAliases().
+ */
+export declare function buildTokenIndex(doc: TokenDocument): Map<string, Token>;
+/**
+ * Resolve a single alias reference. Returns the eventual literal value, or
+ * throws if the reference is unresolvable or cyclic.
+ */
+export declare function resolveReference(reference: string, mode: string, index: Map<string, Token>, seen?: Set<string>): TokenValue;
+/**
+ * Validate every alias in the document. Returns a list of error messages —
+ * empty array means all aliases resolve cleanly.
+ */
+export declare function validateAliases(doc: TokenDocument): string[];
+/**
+ * Format an alias reference for DTCG output. DTCG uses `{path.to.token}`
+ * syntax with curly braces.
+ */
+export declare function formatDtcgReference(referencePath: string[]): string;
+/**
+ * Parse a DTCG alias string back into a path array. Returns null if the
+ * string isn't an alias reference.
+ */
+export declare function parseDtcgReference(s: string): string[] | null;
+//# sourceMappingURL=alias-resolver.d.ts.map

package/dist/core/tokens/alias-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias-resolver.d.ts","sourceRoot":"","sources":["../../../src/core/tokens/alias-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEnE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAStE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,EACzB,IAAI,GAAE,GAAG,CAAC,MAAM,CAAa,GAC5B,UAAU,CAsCZ;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,EAAE,CAqB5D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAI7D"}

package/dist/core/tokens/alias-resolver.js

@@ -0,0 +1,99 @@
+/**
+ * Alias reference resolution and validation.
+ *
+ * DTCG alias references look like `{color.primary}` or `{tier-1.color.blue.500}`.
+ * They can chain (an alias can reference another alias), but cycles are an
+ * error.
+ *
+ * This module:
+ *   - Resolves an alias to its eventual literal value (for formatters that
+ *     can't natively express references — CSS, SCSS, Tailwind).
+ *   - Validates that every alias points to an existing token.
+ *   - Detects cycles.
+ */
+/**
+ * Build a lookup map from dot-path strings (e.g. "color.primary") to Token
+ * objects. Used as the index for resolveAliases().
+ */
+export function buildTokenIndex(doc) {
+    const index = new Map();
+    for (const set of doc.sets) {
+        for (const token of set.tokens) {
+            const key = token.path.join(".");
+            index.set(key, token);
+        }
+    }
+    return index;
+}
+/**
+ * Resolve a single alias reference. Returns the eventual literal value, or
+ * throws if the reference is unresolvable or cyclic.
+ */
+export function resolveReference(reference, mode, index, seen = new Set()) {
+    // Strip the curly braces if present: "{color.primary}" → "color.primary"
+    const path = reference.replace(/^\{|\}$/g, "");
+    if (seen.has(path)) {
+        throw new Error(`[figma-console-mcp] Alias cycle detected: ${[...seen, path].join(" → ")}`);
+    }
+    seen.add(path);
+    const target = index.get(path);
+    if (!target) {
+        throw new Error(`[figma-console-mcp] Unresolvable alias reference: {${path}}`);
+    }
+    // Find the value for the requested mode; fall back to the only mode if
+    // there's just one (alias's target may be single-mode while the source
+    // is multi-mode, or vice versa).
+    const value = target.values[mode] ??
+        (Object.keys(target.values).length === 1
+            ? Object.values(target.values)[0]
+            : undefined);
+    if (!value) {
+        throw new Error(`[figma-console-mcp] Alias {${path}} has no value for mode "${mode}"`);
+    }
+    // Chain: if the target's value is itself an alias, recurse.
+    if (value.reference) {
+        return resolveReference(value.reference, mode, index, seen);
+    }
+    return value;
+}
+/**
+ * Validate every alias in the document. Returns a list of error messages —
+ * empty array means all aliases resolve cleanly.
+ */
+export function validateAliases(doc) {
+    const index = buildTokenIndex(doc);
+    const errors = [];
+    for (const set of doc.sets) {
+        for (const token of set.tokens) {
+            for (const [mode, value] of Object.entries(token.values)) {
+                if (value.reference) {
+                    try {
+                        resolveReference(value.reference, mode, index);
+                    }
+                    catch (err) {
+                        errors.push(`${token.path.join(".")} (mode "${mode}"): ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Format an alias reference for DTCG output. DTCG uses `{path.to.token}`
+ * syntax with curly braces.
+ */
+export function formatDtcgReference(referencePath) {
+    return `{${referencePath.join(".")}}`;
+}
+/**
+ * Parse a DTCG alias string back into a path array. Returns null if the
+ * string isn't an alias reference.
+ */
+export function parseDtcgReference(s) {
+    const match = s.match(/^\{([^}]+)\}$/);
+    if (!match)
+        return null;
+    return match[1].split(".");
+}
+//# sourceMappingURL=alias-resolver.js.map

package/dist/core/tokens/alias-resolver.js.map

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

package/dist/core/tokens/config.d.ts

@@ -0,0 +1,352 @@
+/**
+ * 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 { z } from "zod";
+import type { ConflictResolution, ExportFormat } from "./types.js";
+/**
+ * Schema for a single output target in `tokens.config.json`. Each entry
+ * produces one or more files when figma_export_tokens runs.
+ */
+declare const OutputTargetSchema: z.ZodObject<{
+    format: z.ZodEnum<["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.ZodOptional<z.ZodString>;
+    /** Output prefix applied to every token name (e.g. "ds-", "al-"). */
+    prefix: z.ZodOptional<z.ZodString>;
+    /** Emit one file per mode (e.g. tokens-light.css, tokens-dark.css). */
+    splitByMode: z.ZodOptional<z.ZodBoolean>;
+    /** Emit one file per token set / Figma collection. */
+    splitByCollection: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * 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.ZodOptional<z.ZodBoolean>;
+    /** Per-target transform options. Override the global defaults. */
+    transforms: z.ZodOptional<z.ZodObject<{
+        colorFormat: z.ZodOptional<z.ZodEnum<["hex", "hex8", "rgba", "oklch", "hsl"]>>;
+        sizeUnit: z.ZodOptional<z.ZodEnum<["px", "rem", "pt", "dp"]>>;
+        remBase: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+        sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+        remBase?: number | undefined;
+    }, {
+        colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+        sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+        remBase?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+    resolveAliases?: boolean | undefined;
+    filename?: string | undefined;
+    prefix?: string | undefined;
+    splitByMode?: boolean | undefined;
+    splitByCollection?: boolean | undefined;
+    transforms?: {
+        colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+        sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+        remBase?: number | undefined;
+    } | undefined;
+}, {
+    format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+    resolveAliases?: boolean | undefined;
+    filename?: string | undefined;
+    prefix?: string | undefined;
+    splitByMode?: boolean | undefined;
+    splitByCollection?: boolean | undefined;
+    transforms?: {
+        colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+        sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+        remBase?: number | undefined;
+    } | undefined;
+}>;
+export type OutputTarget = z.infer<typeof OutputTargetSchema>;
+/**
+ * Full schema for `tokens.config.json`. Every field is optional so the
+ * minimum-viable config is `{ "figmaFile": "..." }` — the rest gets sensible
+ * defaults.
+ */
+export declare const TokensConfigSchema: z.ZodObject<{
+    /** Optional JSON Schema URL for editor autocompletion. */
+    $schema: z.ZodOptional<z.ZodString>;
+    /**
+     * 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.ZodOptional<z.ZodString>;
+    /** Where the canonical (committed) token sources live. */
+    source: z.ZodDefault<z.ZodObject<{
+        /** Directory holding the canonical token files. */
+        dir: z.ZodString;
+        /** Glob pattern within dir. Default: "*.tokens.json" */
+        pattern: z.ZodOptional<z.ZodString>;
+        /**
+         * 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.ZodDefault<z.ZodEnum<["dtcg", "tokens-studio"]>>;
+    }, "strip", z.ZodTypeAny, {
+        dir: string;
+        canonical: "dtcg" | "tokens-studio";
+        pattern?: string | undefined;
+    }, {
+        dir: string;
+        pattern?: string | undefined;
+        canonical?: "dtcg" | "tokens-studio" | undefined;
+    }>>;
+    /** Where build outputs (CSS, Tailwind, etc.) get written. */
+    generated: z.ZodOptional<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+        formats: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            format: z.ZodEnum<["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.ZodOptional<z.ZodString>;
+            /** Output prefix applied to every token name (e.g. "ds-", "al-"). */
+            prefix: z.ZodOptional<z.ZodString>;
+            /** Emit one file per mode (e.g. tokens-light.css, tokens-dark.css). */
+            splitByMode: z.ZodOptional<z.ZodBoolean>;
+            /** Emit one file per token set / Figma collection. */
+            splitByCollection: z.ZodOptional<z.ZodBoolean>;
+            /**
+             * 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.ZodOptional<z.ZodBoolean>;
+            /** Per-target transform options. Override the global defaults. */
+            transforms: z.ZodOptional<z.ZodObject<{
+                colorFormat: z.ZodOptional<z.ZodEnum<["hex", "hex8", "rgba", "oklch", "hsl"]>>;
+                sizeUnit: z.ZodOptional<z.ZodEnum<["px", "rem", "pt", "dp"]>>;
+                remBase: z.ZodOptional<z.ZodNumber>;
+            }, "strip", z.ZodTypeAny, {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            }, {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }, {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        dir: string;
+        formats: {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }[];
+    }, {
+        dir?: string | undefined;
+        formats?: {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }[] | undefined;
+    }>>;
+    /** Mode name mappings (Figma mode name → output mode name). */
+    modes: z.ZodOptional<z.ZodObject<{
+        /** e.g. { "Light": "light", "Dark": "dark" } */
+        map: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Default mode if a token has no explicit mode (e.g. "Light"). */
+        default: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        map?: Record<string, string> | undefined;
+        default?: string | undefined;
+    }, {
+        map?: Record<string, string> | undefined;
+        default?: string | undefined;
+    }>>;
+    /** Default conflict-resolution strategy when not specified per-call. */
+    conflictResolution: z.ZodDefault<z.ZodEnum<["ask", "figma-wins", "code-wins", "skip"]>>;
+    /** Behavior for tokens that exist on one side but not the other. */
+    sync: z.ZodOptional<z.ZodObject<{
+        onMissingInCode: z.ZodDefault<z.ZodEnum<["preserve", "delete", "warn"]>>;
+        onMissingInFigma: z.ZodDefault<z.ZodEnum<["preserve", "delete", "warn"]>>;
+    }, "strip", z.ZodTypeAny, {
+        onMissingInCode: "warn" | "delete" | "preserve";
+        onMissingInFigma: "warn" | "delete" | "preserve";
+    }, {
+        onMissingInCode?: "warn" | "delete" | "preserve" | undefined;
+        onMissingInFigma?: "warn" | "delete" | "preserve" | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    source: {
+        dir: string;
+        canonical: "dtcg" | "tokens-studio";
+        pattern?: string | undefined;
+    };
+    conflictResolution: "ask" | "figma-wins" | "code-wins" | "skip";
+    sync?: {
+        onMissingInCode: "warn" | "delete" | "preserve";
+        onMissingInFigma: "warn" | "delete" | "preserve";
+    } | undefined;
+    modes?: {
+        map?: Record<string, string> | undefined;
+        default?: string | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+    figmaFile?: string | undefined;
+    generated?: {
+        dir: string;
+        formats: {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }[];
+    } | undefined;
+}, {
+    sync?: {
+        onMissingInCode?: "warn" | "delete" | "preserve" | undefined;
+        onMissingInFigma?: "warn" | "delete" | "preserve" | undefined;
+    } | undefined;
+    source?: {
+        dir: string;
+        pattern?: string | undefined;
+        canonical?: "dtcg" | "tokens-studio" | undefined;
+    } | undefined;
+    modes?: {
+        map?: Record<string, string> | undefined;
+        default?: string | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+    figmaFile?: string | undefined;
+    generated?: {
+        dir?: string | undefined;
+        formats?: {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }[] | undefined;
+    } | undefined;
+    conflictResolution?: "ask" | "figma-wins" | "code-wins" | "skip" | undefined;
+}>;
+export type TokensConfig = z.infer<typeof TokensConfigSchema>;
+/**
+ * Result of running `loadTokensConfig`. Includes the resolved config plus
+ * provenance info — where the file was found and the absolute project root.
+ */
+export interface LoadedTokensConfig {
+    config: TokensConfig;
+    /** Absolute path to the discovered `tokens.config.json`. */
+    configPath: string;
+    /** Directory containing the config file — used as the project root. */
+    projectRoot: string;
+}
+/**
+ * Walk up from `startDir` looking for `tokens.config.json`. Returns the first
+ * match, or `null` if none found by the filesystem root.
+ */
+export declare function findTokensConfig(startDir: string): string | 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 declare function loadTokensConfig(opts?: {
+    cwd?: string;
+    explicitPath?: string;
+}): LoadedTokensConfig | null;
+/**
+ * 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 declare const DEFAULT_TOKENS_CONFIG: TokensConfig;
+/**
+ * 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 declare function buildSuggestedScaffold(opts: {
+    projectRoot: string;
+    detectedFramework?: "tailwind-v4" | "tailwind-v3" | "css" | "scss" | "ts";
+}): {
+    configContent: string;
+    directories: string[];
+    stylesheetImport: string;
+    nextSteps: string;
+};
+/**
+ * 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 declare function resolveOutputTargets(config: TokensConfig | null, explicitFormat: ExportFormat | undefined): OutputTarget[];
+/**
+ * Resolve the conflict-resolution strategy. Per-call argument wins over config
+ * default, which wins over the global default ("ask").
+ */
+export declare function resolveConflictStrategy(config: TokensConfig | null, perCall: ConflictResolution | undefined): ConflictResolution;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/core/tokens/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/tokens/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEnE;;;GAGG;AACH,QAAA,MAAM,kBAAkB;;IActB,0EAA0E;;IAE1E,qEAAqE;;IAErE,uEAAuE;;IAEvE,sDAAsD;;IAEtD;;;;OAIG;;IAEH,kEAAkE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQlE,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;IAE3B,0DAA0D;;IAE1D;;;;OAIG;;IAEH,0DAA0D;;QAGtD,mDAAmD;;QAEnD,wDAAwD;;QAExD;;;;WAIG;;;;;;;;;;;IAIP,6DAA6D;;;;;YAxD/D,0EAA0E;;YAE1E,qEAAqE;;YAErE,uEAAuE;;YAEvE,sDAAsD;;YAEtD;;;;eAIG;;YAEH,kEAAkE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiDhE,+DAA+D;;QAG3D,gDAAgD;;QAEhD,mEAAmE;;;;;;;;;IAIvE,wEAAwE;;IAIxE,oEAAoE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY7D,CAAC;AAEZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,kBAAkB,GAAG,IAAI,CAwCjC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,YASnC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,aAAa,GAAG,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;CAC3E,GAAG;IACF,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,CAyBA;AA6CD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,cAAc,EAAE,YAAY,GAAG,SAAS,GACvC,YAAY,EAAE,CAWhB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,OAAO,EAAE,kBAAkB,GAAG,SAAS,GACtC,kBAAkB,CAEpB"}