figma-console-mcp 1.33.2 → 1.35.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)
+> **🆕 Figma Slots Support (v1.35.0):** Create, inspect, populate, and reset Figma Slots (GA at Config 2026) programmatically — `figma_create_slot` adds slots to components (variants included), `figma_append_to_slot` populates instance slots with cloned or new content, plus `figma_get_slots`, `figma_reset_slot`, and `figma_add_slot_property`. Live-validated against the GA Plugin API; closes the most-requested issue [#29](https://github.com/southleft/figma-console-mcp/issues/29), based on community PR [#77](https://github.com/southleft/figma-console-mcp/pull/77). **Plugin re-import required** (`code.js` + `ui.html` changed). [See what's new →](CHANGELOG.md#1350---2026-07-09)
 
 ## 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** | **112** | **101** | **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 (101 tools) from web AI clients without Node.js. NPX/Local Git gives the full 112 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 112 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 112 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:** 101 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** | **112** | **101** | **112** | **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 112 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
@@ -427,13 +431,20 @@ When you first use design system tools:
   - Supports markdown formatting for rich documentation
   - Descriptions appear in Dev Mode for developers
 
+### 🧩 Figma Slots (Local Mode + Cloud Mode)
+- `figma_create_slot` - **Add a slot to a component** via the GA `createSlot()` API — the linked SLOT property is created automatically; works on standalone components and variants inside a component set
+- `figma_get_slots` - List slots on a component, component set (aggregated across variants), or instance — ids, names, property keys, dimensions, and current children
+- `figma_append_to_slot` - **Populate an instance's slot** by cloning an existing node or creating new content (`setProperties` rejects slot values by design — this is the population path)
+- `figma_reset_slot` - Clear a slot's content on an instance
+- `figma_add_slot_property` - Retrofit an existing frame as a slot via a manual SLOT property binding, with `description` and `preferredValues`
+
 ### 🔍 Design-Code Parity (All Modes)
 - `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).
+- `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 +457,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 +680,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 112 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 +819,11 @@ 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.35.0 (Stable) - Production-ready. Latest: Figma Slots write support — create, inspect, populate, and reset Slots (GA at Config 2026) via 5 new tools (`figma_create_slot`, `figma_get_slots`, `figma_append_to_slot`, `figma_reset_slot`, `figma_add_slot_property`), live-validated against the GA Plugin API and based on community PR #77. On top of v1.34.0's Bidirectional Token Sync v2 + DTCG 2025.10 — `figma_import_tokens` 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 `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, **112 tools** (Local) / **101 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [x] **v1.35.0** - Figma Slots write support, closing [#29](https://github.com/southleft/figma-console-mcp/issues/29) (the tracker's most-requested feature) via community PR [#77](https://github.com/southleft/figma-console-mcp/pull/77) by @simonesalvucci, updated to the GA API. Five new tools: `figma_create_slot` (slot + auto-linked SLOT property; variants inside component sets supported — the beta restriction was lifted at GA), `figma_get_slots`, `figma_append_to_slot` (clone or create content into instance slots; snaps clones to the slot origin), `figma_reset_slot`, and `figma_add_slot_property` (retrofit an existing frame as a slot). Hardened by live validation: VARIANT `defaultValue` passthrough restored (Figma requires non-empty), destructive-path reorder in the append handler (content validated before `clearExisting` empties anything), relay whitelist fix for `slot` payloads. **Plugin re-import required** (`code.js` + `ui.html` changed).
+- [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 +852,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

@@ -154,6 +154,8 @@ export class CloudWebSocketConnector {
         const params = { nodeId, propertyName, propertyType: type, defaultValue };
         if (options?.preferredValues)
             params.preferredValues = options.preferredValues;
+        if (options?.description)
+            params.description = options.description;
         return this.sendCommand('ADD_COMPONENT_PROPERTY', params);
     }
     async editComponentProperty(nodeId, propertyName, newValue) {
@@ -180,6 +182,39 @@ 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);
+    }
+    // ============================================================================
+    // Slot operations
+    // ============================================================================
+    async createSlot(nodeId, options) {
+        return this.sendCommand('CREATE_SLOT', { nodeId, ...options });
+    }
+    async getSlots(nodeId) {
+        return this.sendCommand('GET_SLOTS', { nodeId });
+    }
+    async appendToSlot(params) {
+        return this.sendCommand('APPEND_TO_SLOT', params);
+    }
+    async resetSlot(params) {
+        return this.sendCommand('RESET_SLOT', params);
+    }
     // ============================================================================
     // Node manipulation
     // ============================================================================

package/dist/cloudflare/core/figma-tools.js

@@ -3229,7 +3229,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
     // Tool 16: Set Instance Properties (Desktop Bridge)
     // Updates component properties on an instance using setProperties()
     // This is the correct way to update TEXT/BOOLEAN/VARIANT properties on component instances
-    server.tool("figma_set_instance_properties", "Update component properties on a component instance. IMPORTANT: Use this tool instead of trying to edit text nodes directly when working with component instances. Components often expose TEXT, BOOLEAN, INSTANCE_SWAP, and VARIANT properties that control their content. Direct text node editing may fail silently if the component uses properties. This tool handles the #nodeId suffix pattern automatically. Requires Desktop Bridge connection.", {
+    server.tool("figma_set_instance_properties", "Update component properties on a component instance. IMPORTANT: Use this tool instead of trying to edit text nodes directly when working with component instances. Components often expose TEXT, BOOLEAN, INSTANCE_SWAP, and VARIANT properties that control their content. SLOT properties CANNOT be set here — use figma_append_to_slot to populate slot content. Direct text node editing may fail silently if the component uses properties. This tool handles the #nodeId suffix pattern automatically. Requires Desktop Bridge connection.", {
         nodeId: z
             .string()
             .describe("ID of the INSTANCE node to update (e.g., '1:234'). Must be a component instance, not a regular frame."),

package/dist/cloudflare/core/slot-tools.js

@@ -0,0 +1,334 @@
+import { z } from "zod";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "slot-tools" });
+const SLOT_LAYOUT_MODES = ["NONE", "HORIZONTAL", "VERTICAL"];
+const SLOT_CHILD_NODE_TYPES = [
+    "FRAME",
+    "RECTANGLE",
+    "ELLIPSE",
+    "TEXT",
+    "LINE",
+    "POLYGON",
+    "STAR",
+    "VECTOR",
+];
+const preferredValueSchema = z.object({
+    type: z.enum(["COMPONENT", "COMPONENT_SET"]).describe("Type of preferred value"),
+    key: z.string().describe("Component or component set key"),
+});
+/**
+ * Register MCP tools for Figma Slots (open beta).
+ * Requires Desktop Bridge and a Figma Desktop version with SlotNode API support.
+ */
+export function registerSlotTools(server, getDesktopConnector) {
+    server.tool("figma_create_slot", `Create a SlotNode inside a component using createSlot(). Automatically creates a linked SLOT component property named after the slot (renaming the slot renames the property). Slots are freeform drop zones for instance content — more flexible than INSTANCE_SWAP. Works on standalone COMPONENTs and variant COMPONENTs inside a COMPONENT_SET (call once per variant). GRID layout is not allowed on slots. Requires Desktop Bridge.`, {
+        nodeId: z
+            .string()
+            .describe("The COMPONENT node ID to add a slot to"),
+        name: z
+            .string()
+            .optional()
+            .describe("Slot layer name (e.g. 'Content', 'Footer')"),
+        width: z
+            .number()
+            .optional()
+            .describe("Initial slot width in pixels"),
+        height: z
+            .number()
+            .optional()
+            .describe("Initial slot height in pixels"),
+        layoutMode: z
+            .enum(SLOT_LAYOUT_MODES)
+            .optional()
+            .describe("Auto-layout mode for the slot (GRID is not supported)"),
+    }, async ({ nodeId, name, width, height, layoutMode }) => {
+        try {
+            const connector = await getDesktopConnector();
+            const result = await connector.createSlot(nodeId, {
+                name,
+                width,
+                height,
+                layoutMode,
+            });
+            if (!result.success) {
+                throw new Error(result.error || "Failed to create slot");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            slot: result.slot,
+                            hint: "Use figma_get_slots to inspect slots. Populate instance slots with figma_append_to_slot (not figma_set_instance_properties).",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_create_slot failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                            hint: "Target a COMPONENT node (standalone or a variant inside a COMPONENT_SET). Ensure Figma Desktop supports Slots.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("figma_get_slots", `List SlotNode children on a component, component set, or instance. Returns slot IDs, names, property keys, dimensions, and current child nodes. Use on instances before figma_append_to_slot to discover slot names/IDs.`, {
+        nodeId: z
+            .string()
+            .describe("COMPONENT, COMPONENT_SET, or INSTANCE node ID"),
+    }, async ({ nodeId }) => {
+        try {
+            const connector = await getDesktopConnector();
+            const result = await connector.getSlots(nodeId);
+            if (!result.success) {
+                throw new Error(result.error || "Failed to get slots");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: true, ...(result.data ?? {}) }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_get_slots failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                            hint: "Ensure the node is a component or instance with slots, and Desktop Bridge is connected.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("figma_append_to_slot", `Add content to a slot on a component instance. Clones sourceNodeId into the slot, or creates a new node (nodeType). SLOT content cannot be set via figma_set_instance_properties — use this tool instead. Widgets, stickies, and raw ComponentNodes cannot be appended to slots.`, {
+        slotId: z
+            .string()
+            .optional()
+            .describe("Direct SlotNode ID (from figma_get_slots)"),
+        instanceId: z
+            .string()
+            .optional()
+            .describe("Instance ID — use with slotName when slotId is unknown"),
+        slotName: z
+            .string()
+            .optional()
+            .describe("Slot layer name on the instance (e.g. 'Content')"),
+        sourceNodeId: z
+            .string()
+            .optional()
+            .describe("Node to clone into the slot (default: clone=true)"),
+        nodeType: z
+            .enum(SLOT_CHILD_NODE_TYPES)
+            .optional()
+            .describe("Create a new node in the slot instead of cloning"),
+        properties: z
+            .record(z.string(), z.union([z.string(), z.number()]))
+            .optional()
+            .describe("Properties for created nodes: name, text, width, height"),
+        clone: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When using sourceNodeId, clone the node (default true). Set false to move."),
+        clearExisting: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Remove existing slot children before appending"),
+    }, async (args) => {
+        try {
+            if (!args.slotId && !(args.instanceId && args.slotName)) {
+                throw new Error("Provide slotId OR (instanceId + slotName)");
+            }
+            if (!args.sourceNodeId && !args.nodeType) {
+                throw new Error("Provide sourceNodeId (clone into slot) or nodeType (create new content)");
+            }
+            const connector = await getDesktopConnector();
+            const result = await connector.appendToSlot(args);
+            if (!result.success) {
+                throw new Error(result.error || "Failed to append to slot");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            slot: result.slot,
+                            appendedNode: result.appendedNode,
+                            hint: "Use figma_capture_screenshot to verify slot content visually.",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_append_to_slot failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                            hints: [
+                                "Use figma_get_slots on the instance to find slot IDs/names",
+                                "Clone instances or frames — not raw ComponentNodes",
+                                "SLOT properties cannot be set via figma_set_instance_properties",
+                            ],
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("figma_reset_slot", `Reset a slot on a component instance to its default (empty) state from the main component. Uses SlotNode.resetSlot().`, {
+        slotId: z
+            .string()
+            .optional()
+            .describe("Direct SlotNode ID"),
+        instanceId: z
+            .string()
+            .optional()
+            .describe("Instance ID — use with slotName when slotId is unknown"),
+        slotName: z
+            .string()
+            .optional()
+            .describe("Slot layer name on the instance"),
+    }, async ({ slotId, instanceId, slotName }) => {
+        try {
+            if (!slotId && !(instanceId && slotName)) {
+                throw new Error("Provide slotId OR (instanceId + slotName)");
+            }
+            const connector = await getDesktopConnector();
+            const result = await connector.resetSlot({ slotId, instanceId, slotName });
+            if (!result.success) {
+                throw new Error(result.error || "Failed to reset slot");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            slot: result.slot,
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_reset_slot failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("figma_add_slot_property", `Manually add a SLOT component property and bind it to an existing frame (alternative to figma_create_slot). The frame must be a direct child of the component, must not use GRID layout, and must not be nested inside another slot. Supports description and preferredValues.`, {
+        nodeId: z.string().describe("COMPONENT or COMPONENT_SET node ID"),
+        propertyName: z.string().describe("Slot property name (e.g. 'Content')"),
+        frameNodeId: z
+            .string()
+            .describe("Frame node ID to bind as the slot content area"),
+        description: z
+            .string()
+            .optional()
+            .describe("Slot property description (SLOT-only)"),
+        preferredValues: z
+            .array(preferredValueSchema)
+            .optional()
+            .describe("Preferred components for slot content (SLOT-only)"),
+    }, async ({ nodeId, propertyName, frameNodeId, description, preferredValues }) => {
+        try {
+            const connector = await getDesktopConnector();
+            const code = `
+const component = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
+if (!component || (component.type !== 'COMPONENT' && component.type !== 'COMPONENT_SET')) {
+  throw new Error('Node must be COMPONENT or COMPONENT_SET');
+}
+const frame = await figma.getNodeByIdAsync(${JSON.stringify(frameNodeId)});
+if (!frame || frame.type !== 'FRAME') {
+  throw new Error('frameNodeId must be a FRAME node');
+}
+// For a COMPONENT the frame must be its direct child. For a COMPONENT_SET the
+// property lives on the set but the frame lives inside a variant COMPONENT —
+// accept a frame whose parent is a variant of this set.
+const directChild = frame.parent === component;
+const variantChild = component.type === 'COMPONENT_SET' &&
+  frame.parent && frame.parent.type === 'COMPONENT' && frame.parent.parent === component;
+if (!directChild && !variantChild) {
+  throw new Error(component.type === 'COMPONENT_SET'
+    ? 'Frame must be a direct child of one of the set\\'s variant components'
+    : 'Frame must be a direct child of the component');
+}
+if (frame.layoutMode === 'GRID') {
+  throw new Error('GRID layoutMode is not allowed on slot frames');
+}
+const options = {};
+${description ? `options.description = ${JSON.stringify(description)};` : ""}
+${preferredValues ? `options.preferredValues = ${JSON.stringify(preferredValues)};` : ""}
+const propKey = component.addComponentProperty(${JSON.stringify(propertyName)}, 'SLOT', '', Object.keys(options).length ? options : undefined);
+// Merge — assigning a fresh object would wipe the frame's existing bindings
+// (e.g. a BOOLEAN property driving 'visible').
+frame.componentPropertyReferences = Object.assign({}, frame.componentPropertyReferences, { slotContentId: propKey });
+return { propertyKey: propKey, frameId: frame.id, frameName: frame.name };
+`;
+            const result = await connector.executeCodeViaUI(code, 10000);
+            if (!result.success) {
+                throw new Error(result.error || "Failed to add slot property");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            result: result.result,
+                            hint: "Prefer figma_create_slot() for new slots — it creates the SlotNode and property automatically.",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_add_slot_property failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

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({