figma-console-mcp 1.33.2 → 1.34.0

package/README.md

@@ -8,16 +8,16 @@
 
 > **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, **debugging**, and **bidirectional token sync**.
 
-> **🆕 Self-healing connection + 33-fix audit (v1.33.0, patched v1.33.1 — security dependency sweep):** The Desktop Bridge now tells the truth and heals itself — the status pill derives from live connection state (it used to glow green with zero MCP servers connected), `/health` auto-discovery reconnects restarted servers without the manual ritual, and a version handshake banners the plugin when it needs a re-import. Underneath: a 33-fix full-codebase audit — lossless DTCG multi-mode round-trips, cross-collection alias resolution, branch-URL correctness across REST tools, cache-poisoning and CSWSH fixes. **Re-import the plugin manifest one more time** — the new handshake makes it the last one you have to discover on your own. [See what's new →](CHANGELOG.md#1330---2026-07-02)
+> **🆕 Bidirectional Token Sync v2 + DTCG 2025.10 (v1.34.0):** `figma_import_tokens` now applies the *whole* diff plan — creates, renames, alias re-targeting, and replace-gated deletes — for a true code→Figma round-trip; exports speak DTCG 2025.10 on request (opt-in, legacy default byte-identical); scopes/codeSyntax round-trip; `figma_setup_design_tokens` accepts alias values; and the new `figma_create_component_set` builds a full variant set from an axes matrix in one call. **Plugin re-import required** (`code.js` + `ui.html` changed). [See what's new →](CHANGELOG.md#1340---2026-07-03)
 
 ## What is this?
 
 Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 - **🎨 Design system extraction** - Pull variables, components, and styles
-- **🔁 Bidirectional token sync** - Export Figma variables to DTCG JSON + CSS custom properties; push code-side edits back to Figma. Replaces Style Dictionary and Tokens Studio's export pipeline.
+- **🔁 Bidirectional token sync** - Export Figma variables to DTCG JSON (legacy or 2025.10 dialect) + 9 more formats; push code-side edits back to Figma with full apply — creates, renames, alias re-targeting, and replace-gated deletes. Replaces Style Dictionary and Tokens Studio's export pipeline.
 - **📸 Visual debugging** - Take screenshots for context
-- **✏️ Design creation** - Create UI components, frames, and layouts directly in Figma
+- **✏️ Design creation** - Create UI components, frames, and layouts directly in Figma — including one-call component-set creation from a variant axes matrix
 - **🔧 Variable management** - Create, update, rename, and delete design tokens
 - **🕰 Version history & time-series awareness** - List versions, diff snapshots, generate markdown changelogs, trace property/variant introduction via binary-search blame
 - **⚡ Real-time monitoring** - Watch console logs from the Desktop Bridge plugin
@@ -55,9 +55,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** | **106** | **95** | **9** |
+| **Total tools available** | **107** | **96** | **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 106 tools with real-time monitoring.
+> **Bottom line:** Remote SSE is **read-only** with 9 tools. **Cloud Mode** unlocks write access (96 tools) from web AI clients without Node.js. NPX/Local Git gives the full 107 tools with real-time monitoring.
 
 ---
 
@@ -65,7 +65,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 106 tools including design creation, variable management, and component instantiation.
+**What you get:** All 107 tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -162,7 +162,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 106 tools as NPX, plus full source code access.
+**What you get:** Same 107 tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -251,7 +251,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:** 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.
+**What you get:** 96 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
 
@@ -308,7 +308,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** | **106** | **95** | **106** | **9** (read-only) |
+| **Total tools** | **107** | **96** | **107** | **9** (read-only) |
 | **Design creation** | ✅ | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
@@ -323,7 +323,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 106 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 107 tools.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -415,6 +415,10 @@ When you first use design system tools:
   - Create frames, shapes, text, components
   - Apply auto-layout, styles, effects
   - Build complete UI mockups programmatically
+- `figma_create_component_set` - **Create a component set with variants in one declarative call**
+  - Generate every variant combination from an axes matrix (e.g. `{ State: ["default", "hover", "disabled"], Size: ["sm", "lg"] }` → 6 variants) off a base component, or combine existing components
+  - `Prop=Value` variant naming, `combineAsVariants` under the hood, optional auto-arranged labeled grid
+  - Returns each variant's key, ready for `figma_instantiate_component`
 - `figma_arrange_component_set` - **Organize variants into professional component sets**
   - Convert multiple component variants into a proper Figma component set
   - Applies native purple dashed border visualization automatically
@@ -432,8 +436,8 @@ When you first use design system tools:
 - `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).
+- `figma_export_tokens` - **Export Figma variables to design token files in your codebase.** Canonical DTCG JSON (legacy hex dialect by default, or DTCG 2025.10 object colors/dimensions via `dtcgDialect: "2025"`) plus CSS, Tailwind v4/v3, SCSS, TS, JSON, Style Dictionary, and Tokens Studio formats. Diff-aware merge against existing source files (only writes what changed). `tokens.config.json` autodiscovery means zero-arg calls after first setup. Scopes and codeSyntax metadata round-trip via `$extensions`. Replaces Style Dictionary and Tokens Studio's export pipeline for popular styling methods.
+- `figma_import_tokens` - **Push code-side token edits back to Figma with a full apply phase.** Diffs against current Figma state, then applies value updates, **creates** missing collections/variables, applies **renames**, writes real **alias** (`VARIABLE_ALIAS`) references, and — only under `strategy: "replace"` — deletes Figma-only variables. Round-trip safe — Figma variable IDs preserved in DTCG `$extensions["figma-console-mcp"]` so renames on either side don't create duplicates. Accepts both DTCG dialects. Dry-run strategy for safe previews. 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
@@ -446,7 +450,7 @@ When you first use design system tools:
 - `figma_rename_mode` - Rename existing modes
 - `figma_batch_create_variables` - Create up to 100 variables in one call (10-50x faster)
 - `figma_batch_update_variables` - Update up to 100 variable values in one call
-- `figma_setup_design_tokens` - Create complete token system (collection + modes + variables) atomically
+- `figma_setup_design_tokens` - Create complete token system (collection + modes + variables) atomically — values accept DTCG brace references (`"{color.blue.600}"`) that resolve to real variable aliases
 
 ### 📌 FigJam Board Tools (Local Mode + Cloud Mode)
 - `figjam_create_sticky` - Create a sticky note with color options
@@ -669,7 +673,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 106 tools work through the WebSocket transport
+- All 107 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).
 
@@ -808,9 +812,10 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.33.2 (Stable) - Production-ready. Latest: version-handshake fix — the plugin's "update available" banner now compares against the plugin files the server actually ships, so server-only releases no longer nag you to re-import an already-current plugin. On top of the v1.33.1 security dependency sweep (all runtime + critical alerts resolved via in-range bumps; zero API changes) and the v1.33.0 connection UX overhaul (honest status pill derived from live connection state, `/health` auto-discovery with self-healing reconnect, version handshake with in-plugin re-import banner) + a 33-fix full-codebase audit (lossless DTCG multi-mode round-trips, cross-collection alias resolution, branch-URL correctness across REST tools, cache-poisoning and CSWSH fixes, bridge-first screenshots). Built on WCAG-accurate accessibility auditing (line height below 1.5× is no longer mis-flagged as a failure; readability hints decoupled from conformance checks and scoped to multi-line text; code-side WCAG 1.4.12 check), a self-healing Desktop Bridge connection (zombie-process reaper + auto-reconnect watchdog — fixes the recurring "not connected until restart" bug), native variable binding on fills/strokes + typography control in the write tools, shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **106 tools** (Local) / **95 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
+**Current Status:** v1.34.0 (Stable) - Production-ready. Latest: Bidirectional Token Sync v2 + DTCG 2025.10 — `figma_import_tokens` now applies the complete diff plan (creates missing collections/variables, applies renames, writes real `VARIABLE_ALIAS` references, and deletes only under explicit `replace`), `figma_export_tokens` speaks the DTCG 2025.10 dialect on request (legacy default byte-identical), variable scopes/codeSyntax round-trip via `$extensions`, `figma_setup_design_tokens` accepts alias values via DTCG brace references, and the new `figma_create_component_set` builds a full variant set from an axes matrix in one call. On top of the v1.33.x line: version-handshake fix (re-import banner only fires when plugin files actually changed), security dependency sweep, and the v1.33.0 connection UX overhaul (honest status pill derived from live connection state, `/health` auto-discovery with self-healing reconnect) + a 33-fix full-codebase audit (lossless DTCG multi-mode round-trips, cross-collection alias resolution, branch-URL correctness across REST tools, cache-poisoning and CSWSH fixes, bridge-first screenshots). Built on WCAG-accurate accessibility auditing (line height below 1.5× is no longer mis-flagged as a failure; readability hints decoupled from conformance checks and scoped to multi-line text; code-side WCAG 1.4.12 check), a self-healing Desktop Bridge connection (zombie-process reaper + auto-reconnect watchdog — fixes the recurring "not connected until restart" bug), native variable binding on fills/strokes + typography control in the write tools, shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **107 tools** (Local) / **96 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [x] **v1.34.0** - Bidirectional Token Sync v2 + DTCG 2025.10. `figma_import_tokens` now applies the *complete* diff plan: missing collections and variables are created (with modes, inferred/recorded types, and values set in dependency order — aliases in a second pass), token-path renames route to the update phase by round-trip variable ID (no more create+delete pairs that would permanently destroy the original under `replace`), reference values write real `{ type: "VARIABLE_ALIAS", id }` payloads via a four-tier resolver, and deletes are strictly gated behind `strategy: "replace"`. `figma_export_tokens` gains `dtcgDialect: "2025"` (object-form colors from full-precision floats, object dimensions) while the legacy default stays byte-identical; import accepts both dialects unconditionally with dialect-insensitive diff normalization. Variable `scopes` + `codeSyntax` round-trip through `$extensions["figma-console-mcp"]`. `figma_setup_design_tokens` accepts DTCG brace references (`"{color.blue.600}"`) that resolve to real aliases, including forward references. New tool `figma_create_component_set` builds a variant set from an axes matrix (or combines existing components) with `Prop=Value` naming, optional auto-arranged grid, and variant keys in the response — with count-scaled timeouts and rollback on failure. **Plugin re-import required** (`code.js` + `ui.html` changed — the component-set handler and relay). 183 tests across the token/write-tools suites.
 - [x] **v1.33.2** - Version-handshake false-positive fix. The v1.33.0 handshake compared the plugin's reported version against the server's *package* version, so server-only releases (like the v1.33.1 dependency sweep) flagged every up-to-date plugin as stale and pushed the re-import banner for files that hadn't changed. The server now compares against the `PLUGIN_VERSION` embedded in the `figma-desktop-bridge/code.js` it ships — exactly what a re-import would install — and `PLUGIN_VERSION` itself now means "last release in which plugin files changed" (release tooling bumps it only when `figma-desktop-bridge/` actually changed since the last tag). `figma_get_status` gains `transport.websocket.bundledPluginVersion`; `figma_diagnose` blames the right version. No new tools, **no plugin re-import required** (one-time exception: if you re-imported at v1.33.1, the banner appears once more — clear it with one final re-import). 1245 tests passing (9 new).
 - [x] **v1.33.1** - Security dependency sweep. All runtime and critical npm audit alerts resolved via in-range bumps (`ws` 8.21.0, `hono` 4.12.27, `undici` 7.28.0, `handlebars` 4.7.9 — the lone critical, dev-only — plus `lodash`, `path-to-regexp`, `basic-ftp`, `fast-uri`, `vite`). `wrangler` deliberately held at 4.72.0 because newer versions require Node ≥22; the only residual audit findings are inside wrangler/miniflare's dev-time toolchain, which never ships in the npm package or Worker bundle. Supersedes dependabot PRs #81/#82/#84. No code changes, no API changes, no plugin re-import. 1236 tests passing unchanged.
 - [x] **v1.33.0** - Connection UX overhaul + full-codebase audit. The plugin's status pill now derives from live connection state instead of Figma's variables loading (it used to glow green with zero MCP servers connected); HTTP `/health` auto-discovery reconnects restarted servers automatically (including one-dead-among-live, previously a permanent dead end); a version handshake banners the plugin UI when a re-import is needed and surfaces the mismatch in `figma_get_status`/`figma_diagnose`; cloud pairing config survives plugin reopen and its status line is derived + labeled (no more orphaned "Disconnected" under a green pill); all plugin copy is designer-language. The audit fixed 33 verified issues: lossless DTCG multi-mode round-trips, set-qualified cross-collection aliases, TIMING/EASING mapped to DTCG `duration`/`cubicBezier`, two cache-poisoning bugs (the "search returns 0 components" reports), a CSWSH origin bypass (`startsWith` → exact match), post-sleep reaper kill-safety (plus a shell-free `/health` probe with `os.devNull` so Windows curl can't false-negative a healthy sibling), branch-URL correctness across REST tools, and bridge-first `figma_take_screenshot`. `figma_arrange_component_set` now rearranges variants in place so placed instances survive. No new tools; **plugin re-import required** (`code.js` + `ui.html` changed — and the new handshake makes this the last one you have to discover on your own). 1236 tests passing (33 new).
@@ -839,7 +844,8 @@ The architecture supports adding new apps with minimal boilerplate — each app
 - [x] **v1.7.0** - MCP Apps (Token Browser, Design System Dashboard), batch variable operations, design-code parity tools.
 
 **Coming Next:**
-- [ ] **Token sync — parsers + import-side apply expansion** - Parsers for non-DTCG input (Tokens Studio, CSS vars, Tailwind v4, Tailwind v3 config, SCSS, Style Dictionary v3, JSON flat/nested). Plus `toCreate` apply orchestration, `toDelete` for `replace` strategy, alias-target updates, and cross-library variable resolution via `getVariableByIdAsync` so cross-library aliases render as real `var(--target)` references instead of comments.
+- [ ] **Token sync — non-DTCG input parsers** - Parsers for non-DTCG input (Tokens Studio, CSS vars, Tailwind v4, Tailwind v3 config, SCSS, Style Dictionary v3, JSON flat/nested) so `figma_import_tokens` can ingest the same formats it exports. (The import-side apply expansion — creates, replace-gated deletes, alias-target updates — shipped in v1.34.0.)
+- [ ] **Cross-library variable resolution** - Resolve cross-library aliases via `getVariableByIdAsync` so they render as real `var(--target)` references in exports instead of comments.
 - [ ] **Component template library** - Common UI pattern generation
 - [ ] **Visual regression testing** - Screenshot diff capabilities
 

package/dist/cloudflare/core/cloud-websocket-connector.js

@@ -180,6 +180,24 @@ export class CloudWebSocketConnector {
         }
         return this.sendCommand('INSTANTIATE_COMPONENT', params);
     }
+    async createComponentSet(params) {
+        // Timeout scales with variant count — the plugin builds all variants in
+        // one uncancellable pass, so a fixed 30s ceiling on big matrices reports
+        // failure while the set still gets created (retry → duplicates).
+        // Mirrors componentSetTimeoutMs in websocket-connector.ts (not imported:
+        // that module pulls the Node 'ws' stack into the Workers bundle).
+        let variantCount = 1;
+        if (params.componentIds?.length) {
+            variantCount = params.componentIds.length;
+        }
+        else if (params.properties) {
+            for (const values of Object.values(params.properties)) {
+                variantCount *= Math.max(1, values?.length ?? 1);
+            }
+        }
+        const timeout = Math.min(120000, Math.max(30000, variantCount * 1200)) + 5000;
+        return this.sendCommand('CREATE_COMPONENT_SET', params, timeout);
+    }
     // ============================================================================
     // Node manipulation
     // ============================================================================

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

@@ -37,6 +37,19 @@ export function slugifySetName(name) {
  * a `warnings` array get one warning per ambiguous bare path.
  */
 export function buildTokenIndex(doc, warnings) {
+    const index = new Map();
+    for (const [key, entry] of buildTokenLookup(doc, warnings)) {
+        index.set(key, entry.token);
+    }
+    return index;
+}
+/**
+ * Set-aware variant of buildTokenIndex — identical key scheme and ambiguity
+ * rules (set-qualified keys always; bare-path fallback only when unambiguous
+ * across sets), but each entry carries the owning set's name alongside the
+ * token. buildTokenIndex delegates to this so the two can never drift.
+ */
+export function buildTokenLookup(doc, warnings) {
     const index = new Map();
     // barePath → owning entries, used to detect cross-set ambiguity.
     const bareOwners = new Map();
@@ -44,7 +57,7 @@ export function buildTokenIndex(doc, warnings) {
         const setKey = slugifySetName(set.name);
         for (const token of set.tokens) {
             const bare = token.path.join(".");
-            index.set(`${setKey}.${bare}`, token);
+            index.set(`${setKey}.${bare}`, { setName: set.name, token });
             const owners = bareOwners.get(bare) ?? [];
             owners.push({ setName: set.name, token });
             bareOwners.set(bare, owners);
@@ -55,7 +68,7 @@ export function buildTokenIndex(doc, warnings) {
     for (const [bare, owners] of bareOwners) {
         if (owners.length === 1) {
             if (!index.has(bare))
-                index.set(bare, owners[0].token);
+                index.set(bare, owners[0]);
         }
         else if (warnings) {
             warnings.push(`Token path "${bare}" exists in multiple collections (${owners

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

@@ -42,6 +42,16 @@ const OutputTargetSchema = z.object({
      * for CSS/SCSS/Tailwind/etc. since they can't natively express aliases).
      */
     resolveAliases: z.boolean().optional(),
+    /**
+     * DTCG dialect for dtcg/json outputs. 'legacy' (default): hex-string
+     * colors and bare-number dimensions, maximum compatibility (Style
+     * Dictionary v4, Tokens Studio). '2025': DTCG 2025.10 object colors
+     * ({ colorSpace, components, alpha?, hex }) and dimensions
+     * ({ value, unit }) for Style Dictionary v5+ and other 2025.10-aware
+     * tooling. Ignored by css/scss/tailwind/ts formatters, which render
+     * final code.
+     */
+    dtcgDialect: z.enum(["legacy", "2025"]).optional(),
     /** Per-target transform options. Override the global defaults. */
     transforms: z
         .object({

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

@@ -0,0 +1,232 @@
+/**
+ * DTCG dialect helpers — legacy vs 2025.10 value encodings.
+ *
+ * The token pipeline historically speaks the "legacy" DTCG dialect: colors
+ * as hex strings ("#4085F2"), FLOAT dimensions as bare numbers. The DTCG
+ * 2025.10 spec (https://tr.designtokens.org/format/) switched to object
+ * forms:
+ *
+ *   color     = { colorSpace: "srgb", components: [r, g, b], alpha?, hex? }
+ *   dimension = { value: number, unit: "px" | "rem" }
+ *   duration  = { value: number, unit: "ms" | "s" }   (we already emit this)
+ *
+ * Export stays legacy by default (downstream consumers depend on it) and
+ * opts into 2025 via the `dtcgDialect` option. Import accepts BOTH dialects
+ * unconditionally. This module centralizes:
+ *
+ *   - 2025 encoding helpers used by the dtcg/json formatters at render time
+ *   - dialect-agnostic canonicalization used by the import diff so a 2025
+ *     color object compares equal to the same color's legacy hex string
+ *     (both are quantized to 1/255 per channel, tolerating the 8-bit
+ *     precision loss inherent to hex)
+ *   - stripping of the transient `rawColor` field the converter carries on
+ *     COLOR TokenValues (full-precision floats for 2025 components) so it
+ *     never leaks into serialized output
+ */
+export function clamp01(n) {
+    if (Number.isNaN(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+function byteHex(f) {
+    return Math.round(clamp01(f) * 255)
+        .toString(16)
+        .padStart(2, "0");
+}
+/**
+ * Canonicalize any color-like literal to a lowercase 8-digit hex string
+ * (`#rrggbbaa`), or return null when the literal isn't recognizably a color.
+ *
+ * Accepts:
+ *   - hex strings: #rgb, #rrggbb, #rrggbbaa
+ *   - 2025.10 color objects with srgb (or unspecified) colorSpace +
+ *     3 numeric components (+ optional alpha)
+ *   - color objects with a hex fallback field (any colorSpace) + optional alpha
+ *
+ * Both the components form and the hex form quantize to 1 / 255 per channel,
+ * so a full-precision components array compares equal to the hex string the
+ * legacy pipeline derived from the same Figma floats.
+ */
+export function colorLiteralToCanonicalHex(literal) {
+    if (typeof literal === "string") {
+        const m = literal
+            .trim()
+            .match(/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+        if (!m)
+            return null;
+        let digits = m[1].toLowerCase();
+        if (digits.length === 3) {
+            digits = digits
+                .split("")
+                .map((c) => c + c)
+                .join("");
+        }
+        if (digits.length === 6)
+            digits += "ff";
+        return `#${digits}`;
+    }
+    if (literal && typeof literal === "object" && !Array.isArray(literal)) {
+        const o = literal;
+        const colorSpace = typeof o.colorSpace === "string" ? o.colorSpace : undefined;
+        const comps = o.components;
+        if ((colorSpace === undefined || colorSpace === "srgb") &&
+            Array.isArray(comps) &&
+            comps.length === 3 &&
+            comps.every((c) => typeof c === "number")) {
+            const [r, g, b] = comps;
+            const a = typeof o.alpha === "number" ? o.alpha : 1;
+            return `#${byteHex(r)}${byteHex(g)}${byteHex(b)}${byteHex(a)}`;
+        }
+        if (typeof o.hex === "string") {
+            const base = colorLiteralToCanonicalHex(o.hex);
+            if (!base)
+                return null;
+            if (typeof o.alpha === "number") {
+                return base.slice(0, 7) + byteHex(o.alpha);
+            }
+            return base;
+        }
+    }
+    return null;
+}
+/**
+ * Parse a hex color string to raw rgba floats (0–1). Returns null on
+ * anything that isn't a valid 3/6/8-digit hex string.
+ */
+export function hexToRawRgba(hex) {
+    const canonical = colorLiteralToCanonicalHex(hex);
+    if (!canonical)
+        return null;
+    const d = canonical.slice(1);
+    return {
+        r: parseInt(d.slice(0, 2), 16) / 255,
+        g: parseInt(d.slice(2, 4), 16) / 255,
+        b: parseInt(d.slice(4, 6), 16) / 255,
+        a: parseInt(d.slice(6, 8), 16) / 255,
+    };
+}
+/**
+ * Encode a color TokenValue in the DTCG 2025.10 object form.
+ *
+ * Prefers the converter's transient `rawColor` floats (full precision — NOT
+ * round-tripped through 8-bit hex); falls back to parsing a hex-string
+ * literal. Literals already in object form pass through verbatim. Returns
+ * null when the value can't be encoded (caller keeps the legacy rendering).
+ *
+ * `alpha` is emitted only when < 1; `hex` is always included as the interop
+ * courtesy field (#RRGGBB, alpha carried separately).
+ */
+export function colorValueTo2025(value) {
+    const lit = value.literal;
+    if (lit && typeof lit === "object" && !Array.isArray(lit)) {
+        // Already object-form (e.g. a re-exported 2025 document) — pass through.
+        const o = lit;
+        if ("colorSpace" in o || "components" in o || "hex" in o)
+            return o;
+        return null;
+    }
+    let floats = value.rawColor ?? null;
+    if (!floats && typeof lit === "string") {
+        floats = hexToRawRgba(lit);
+    }
+    if (!floats)
+        return null;
+    const { r, g, b, a } = floats;
+    return {
+        colorSpace: "srgb",
+        components: [r, g, b],
+        ...(a < 1 ? { alpha: a } : {}),
+        hex: `#${byteHex(r)}${byteHex(g)}${byteHex(b)}`.toUpperCase(),
+    };
+}
+/**
+ * Encode a dimension literal in the DTCG 2025.10 object form. The converter
+ * emits Figma FLOAT dimensions as bare unitless numbers conventionally
+ * interpreted as px (the same convention the css/json formatters use), so
+ * only bare finite numbers are converted; everything else (unit strings,
+ * pre-encoded objects) keeps its current rendering.
+ */
+export function dimensionLiteralTo2025(literal) {
+    if (typeof literal === "number" && Number.isFinite(literal)) {
+        return { value: literal, unit: "px" };
+    }
+    return null;
+}
+/**
+ * Normalize a TokenValue to a dialect-agnostic comparable form for diffing:
+ *
+ *   - the transient `rawColor` field is dropped (Figma-side values carry it;
+ *     parsed code-side values never do)
+ *   - color-like literals (hex strings OR 2025 color objects) normalize to a
+ *     lowercase 8-digit hex string, quantized to 1/255 per channel
+ *   - `{ value, unit }` objects with px/ms normalize to the bare number
+ *     ("s" converts to ms first), so `{value: 16, unit: "px"}` equals 16 and
+ *     `{value: 0.3, unit: "s"}` equals `{value: 300, unit: "ms"}`
+ *   - "16px"-style strings normalize to the bare number
+ *
+ * Conservative by design: anything not confidently recognized is returned
+ * unchanged (minus rawColor), falling back to the existing deep comparison.
+ */
+export function canonicalizeTokenValueForComparison(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return v;
+    const obj = v;
+    if (!("literal" in obj) && !("reference" in obj))
+        return v;
+    const { rawColor: _rawColor, ...rest } = obj;
+    if (rest.literal !== undefined) {
+        const hex = colorLiteralToCanonicalHex(rest.literal);
+        if (hex !== null)
+            return { ...rest, literal: hex };
+        const num = numericLiteralToCanonical(rest.literal);
+        if (num !== null)
+            return { ...rest, literal: num };
+    }
+    return rest;
+}
+/**
+ * Normalize dimension/duration-shaped literals to a bare comparable number:
+ *   - `{ value: n, unit: "px" | "ms" }` → n
+ *   - `{ value: n, unit: "s" }` → n * 1000 (canonical ms)
+ *   - `"16px"` strings → 16
+ * Returns null for everything else (including rem/em/% and objects with
+ * extra fields — those keep structural comparison).
+ */
+function numericLiteralToCanonical(literal) {
+    if (typeof literal === "string") {
+        const m = literal.trim().match(/^(-?(?:\d+\.?\d*|\.\d+))px$/i);
+        return m ? Number(m[1]) : null;
+    }
+    if (literal &&
+        typeof literal === "object" &&
+        !Array.isArray(literal) &&
+        Object.keys(literal).length === 2) {
+        const o = literal;
+        if (typeof o.value === "number" && typeof o.unit === "string") {
+            if (o.unit === "px" || o.unit === "ms")
+                return o.value;
+            if (o.unit === "s")
+                return o.value * 1000;
+        }
+    }
+    return null;
+}
+/**
+ * Return a copy of a mode-keyed TokenValue map with the transient `rawColor`
+ * field removed from every entry. Used wherever values get serialized
+ * (lastSyncedValue snapshots, diff-plan samples) so the transient field never
+ * appears in output — keeping legacy output byte-identical.
+ */
+export function stripRawColorFromValues(values) {
+    const out = {};
+    for (const [k, v] of Object.entries(values)) {
+        if (v && typeof v === "object" && "rawColor" in v) {
+            const { rawColor: _rawColor, ...rest } = v;
+            out[k] = rest;
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}

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

@@ -12,6 +12,7 @@
  * $extensions["figma-console-mcp"] for round-trip non-destructiveness.
  */
 import { slugifySetName } from "./alias-resolver.js";
+import { stripRawColorFromValues } from "./dialect.js";
 /**
  * Convert a Figma variables payload to our canonical TokenDocument.
  */
@@ -126,14 +127,35 @@ function convertVariable(variable, wantedModes, variableById, collectionNameById
                 // reconstruct it.
                 ...(strippedTypeSuffix ? { figmaName: variable.name } : {}),
                 ...(Object.keys(springByMode).length > 0 ? { spring: springByMode } : {}),
+                // Scopes: stash only when NON-default. ["ALL_SCOPES"] (Figma's
+                // default) and empty/absent arrays are omitted so pre-existing
+                // exports stay byte-identical. codeSyntax: stash only when
+                // non-empty, same reasoning.
+                ...(hasNonDefaultScopes(variable.scopes)
+                    ? { scopes: [...variable.scopes] }
+                    : {}),
+                ...(variable.codeSyntax && Object.keys(variable.codeSyntax).length > 0
+                    ? { codeSyntax: { ...variable.codeSyntax } }
+                    : {}),
                 lastSyncedAt: new Date().toISOString(),
                 // We snapshot the synced value so future merge calls can detect
-                // two-sided conflicts.
-                lastSyncedValue: { ...values },
+                // two-sided conflicts. rawColor is transient render-time data and
+                // must not leak into serialized extensions (legacy output stays
+                // byte-identical).
+                lastSyncedValue: stripRawColorFromValues({ ...values }),
             },
         },
     };
 }
+/**
+ * True when a variable's scopes array is meaningfully restrictive — i.e.
+ * present, non-empty, and not just the default ["ALL_SCOPES"].
+ */
+function hasNonDefaultScopes(scopes) {
+    if (!Array.isArray(scopes) || scopes.length === 0)
+        return false;
+    return !(scopes.length === 1 && scopes[0] === "ALL_SCOPES");
+}
 function mapResolvedType(resolvedType, variableName, warnings) {
     switch (resolvedType) {
         case "COLOR":
@@ -212,7 +234,19 @@ function convertValue(rawValue, variable, modeName, variableById, collectionName
     // Literal values per type.
     if (resolvedType === "COLOR") {
         if (typeof rawValue === "object" && rawValue !== null && "r" in rawValue) {
-            return { literal: rgbaToHex(rawValue) };
+            // The hex string stays the literal (legacy dialect + back-compat), but
+            // we also carry the raw full-precision floats so the 2025.10 dialect
+            // can emit `components` without round-tripping through 8-bit hex.
+            // `rawColor` is transient — see TokenValue.rawColor in types.ts.
+            return {
+                literal: rgbaToHex(rawValue),
+                rawColor: {
+                    r: rawValue.r,
+                    g: rawValue.g,
+                    b: rawValue.b,
+                    a: rawValue.a ?? 1,
+                },
+            };
         }
         warnings.push(`COLOR value isn't an RGB object: ${JSON.stringify(rawValue)}`);
         return { literal: String(rawValue) };