figma-console-mcp 1.26.0 → 1.27.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -26
- package/dist/core/tokens/alias-resolver.d.ts +40 -0
- package/dist/core/tokens/alias-resolver.d.ts.map +1 -0
- package/dist/core/tokens/alias-resolver.js +99 -0
- package/dist/core/tokens/alias-resolver.js.map +1 -0
- package/dist/core/tokens/config.d.ts +352 -0
- package/dist/core/tokens/config.d.ts.map +1 -0
- package/dist/core/tokens/config.js +285 -0
- package/dist/core/tokens/config.js.map +1 -0
- package/dist/core/tokens/figma-converter.d.ts +81 -0
- package/dist/core/tokens/figma-converter.d.ts.map +1 -0
- package/dist/core/tokens/figma-converter.js +196 -0
- package/dist/core/tokens/figma-converter.js.map +1 -0
- package/dist/core/tokens/formatters/css-vars.d.ts +24 -0
- package/dist/core/tokens/formatters/css-vars.d.ts.map +1 -0
- package/dist/core/tokens/formatters/css-vars.js +330 -0
- package/dist/core/tokens/formatters/css-vars.js.map +1 -0
- package/dist/core/tokens/formatters/dtcg.d.ts +28 -0
- package/dist/core/tokens/formatters/dtcg.d.ts.map +1 -0
- package/dist/core/tokens/formatters/dtcg.js +301 -0
- package/dist/core/tokens/formatters/dtcg.js.map +1 -0
- package/dist/core/tokens/formatters/index.d.ts +30 -0
- package/dist/core/tokens/formatters/index.d.ts.map +1 -0
- package/dist/core/tokens/formatters/index.js +46 -0
- package/dist/core/tokens/formatters/index.js.map +1 -0
- package/dist/core/tokens/formatters/json.d.ts +5 -0
- package/dist/core/tokens/formatters/json.d.ts.map +1 -0
- package/dist/core/tokens/formatters/json.js +8 -0
- package/dist/core/tokens/formatters/json.js.map +1 -0
- package/dist/core/tokens/formatters/less.d.ts +4 -0
- package/dist/core/tokens/formatters/less.d.ts.map +1 -0
- package/dist/core/tokens/formatters/less.js +5 -0
- package/dist/core/tokens/formatters/less.js.map +1 -0
- package/dist/core/tokens/formatters/scss.d.ts +4 -0
- package/dist/core/tokens/formatters/scss.d.ts.map +1 -0
- package/dist/core/tokens/formatters/scss.js +5 -0
- package/dist/core/tokens/formatters/scss.js.map +1 -0
- package/dist/core/tokens/formatters/stubs.d.ts +9 -0
- package/dist/core/tokens/formatters/stubs.d.ts.map +1 -0
- package/dist/core/tokens/formatters/stubs.js +12 -0
- package/dist/core/tokens/formatters/stubs.js.map +1 -0
- package/dist/core/tokens/formatters/style-dictionary-v3.d.ts +4 -0
- package/dist/core/tokens/formatters/style-dictionary-v3.d.ts.map +1 -0
- package/dist/core/tokens/formatters/style-dictionary-v3.js +5 -0
- package/dist/core/tokens/formatters/style-dictionary-v3.js.map +1 -0
- package/dist/core/tokens/formatters/tailwind-v3.d.ts +4 -0
- package/dist/core/tokens/formatters/tailwind-v3.d.ts.map +1 -0
- package/dist/core/tokens/formatters/tailwind-v3.js +5 -0
- package/dist/core/tokens/formatters/tailwind-v3.js.map +1 -0
- package/dist/core/tokens/formatters/tailwind-v4.d.ts +4 -0
- package/dist/core/tokens/formatters/tailwind-v4.d.ts.map +1 -0
- package/dist/core/tokens/formatters/tailwind-v4.js +5 -0
- package/dist/core/tokens/formatters/tailwind-v4.js.map +1 -0
- package/dist/core/tokens/formatters/tokens-studio.d.ts +4 -0
- package/dist/core/tokens/formatters/tokens-studio.d.ts.map +1 -0
- package/dist/core/tokens/formatters/tokens-studio.js +5 -0
- package/dist/core/tokens/formatters/tokens-studio.js.map +1 -0
- package/dist/core/tokens/formatters/ts-module.d.ts +4 -0
- package/dist/core/tokens/formatters/ts-module.d.ts.map +1 -0
- package/dist/core/tokens/formatters/ts-module.js +5 -0
- package/dist/core/tokens/formatters/ts-module.js.map +1 -0
- package/dist/core/tokens/index.d.ts +17 -0
- package/dist/core/tokens/index.d.ts.map +1 -0
- package/dist/core/tokens/index.js +16 -0
- package/dist/core/tokens/index.js.map +1 -0
- package/dist/core/tokens/parsers/css-vars.d.ts +3 -0
- package/dist/core/tokens/parsers/css-vars.d.ts.map +1 -0
- package/dist/core/tokens/parsers/css-vars.js +5 -0
- package/dist/core/tokens/parsers/css-vars.js.map +1 -0
- package/dist/core/tokens/parsers/dtcg.d.ts +21 -0
- package/dist/core/tokens/parsers/dtcg.d.ts.map +1 -0
- package/dist/core/tokens/parsers/dtcg.js +254 -0
- package/dist/core/tokens/parsers/dtcg.js.map +1 -0
- package/dist/core/tokens/parsers/index.d.ts +37 -0
- package/dist/core/tokens/parsers/index.d.ts.map +1 -0
- package/dist/core/tokens/parsers/index.js +139 -0
- package/dist/core/tokens/parsers/index.js.map +1 -0
- package/dist/core/tokens/parsers/json.d.ts +4 -0
- package/dist/core/tokens/parsers/json.d.ts.map +1 -0
- package/dist/core/tokens/parsers/json.js +8 -0
- package/dist/core/tokens/parsers/json.js.map +1 -0
- package/dist/core/tokens/parsers/scss.d.ts +3 -0
- package/dist/core/tokens/parsers/scss.d.ts.map +1 -0
- package/dist/core/tokens/parsers/scss.js +5 -0
- package/dist/core/tokens/parsers/scss.js.map +1 -0
- package/dist/core/tokens/parsers/stubs.d.ts +11 -0
- package/dist/core/tokens/parsers/stubs.d.ts.map +1 -0
- package/dist/core/tokens/parsers/stubs.js +14 -0
- package/dist/core/tokens/parsers/stubs.js.map +1 -0
- package/dist/core/tokens/parsers/style-dictionary-v3.d.ts +3 -0
- package/dist/core/tokens/parsers/style-dictionary-v3.d.ts.map +1 -0
- package/dist/core/tokens/parsers/style-dictionary-v3.js +5 -0
- package/dist/core/tokens/parsers/style-dictionary-v3.js.map +1 -0
- package/dist/core/tokens/parsers/tailwind-v3.d.ts +3 -0
- package/dist/core/tokens/parsers/tailwind-v3.d.ts.map +1 -0
- package/dist/core/tokens/parsers/tailwind-v3.js +5 -0
- package/dist/core/tokens/parsers/tailwind-v3.js.map +1 -0
- package/dist/core/tokens/parsers/tailwind-v4.d.ts +3 -0
- package/dist/core/tokens/parsers/tailwind-v4.d.ts.map +1 -0
- package/dist/core/tokens/parsers/tailwind-v4.js +5 -0
- package/dist/core/tokens/parsers/tailwind-v4.js.map +1 -0
- package/dist/core/tokens/parsers/tokens-studio.d.ts +3 -0
- package/dist/core/tokens/parsers/tokens-studio.d.ts.map +1 -0
- package/dist/core/tokens/parsers/tokens-studio.js +5 -0
- package/dist/core/tokens/parsers/tokens-studio.js.map +1 -0
- package/dist/core/tokens/schemas.d.ts +152 -0
- package/dist/core/tokens/schemas.d.ts.map +1 -0
- package/dist/core/tokens/schemas.js +149 -0
- package/dist/core/tokens/schemas.js.map +1 -0
- package/dist/core/tokens/transforms/color.d.ts +9 -0
- package/dist/core/tokens/transforms/color.d.ts.map +1 -0
- package/dist/core/tokens/transforms/color.js +13 -0
- package/dist/core/tokens/transforms/color.js.map +1 -0
- package/dist/core/tokens/transforms/index.d.ts +36 -0
- package/dist/core/tokens/transforms/index.d.ts.map +1 -0
- package/dist/core/tokens/transforms/index.js +30 -0
- package/dist/core/tokens/transforms/index.js.map +1 -0
- package/dist/core/tokens/transforms/size.d.ts +7 -0
- package/dist/core/tokens/transforms/size.d.ts.map +1 -0
- package/dist/core/tokens/transforms/size.js +8 -0
- package/dist/core/tokens/transforms/size.js.map +1 -0
- package/dist/core/tokens/types.d.ts +228 -0
- package/dist/core/tokens/types.d.ts.map +1 -0
- package/dist/core/tokens/types.js +19 -0
- package/dist/core/tokens/types.js.map +1 -0
- package/dist/core/tokens-tools.d.ts +42 -0
- package/dist/core/tokens-tools.d.ts.map +1 -0
- package/dist/core/tokens-tools.js +850 -0
- package/dist/core/tokens-tools.js.map +1 -0
- package/dist/local.d.ts.map +1 -1
- package/dist/local.js +14 -3
- package/dist/local.js.map +1 -1
- package/figma-desktop-bridge/code.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,21 +6,25 @@
|
|
|
6
6
|
[](https://docs.figma-console-mcp.southleft.com)
|
|
7
7
|
[](https://github.com/sponsors/southleft)
|
|
8
8
|
|
|
9
|
-
> **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**, and **
|
|
9
|
+
> **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**.
|
|
10
10
|
|
|
11
|
-
> **🆕
|
|
11
|
+
> **🆕 Bidirectional Token Sync (v1.27.0):** Two new tools — `figma_export_tokens` and `figma_import_tokens` — replace Style Dictionary and Tokens Studio's export pipeline for popular styling methods. Pull every variable across every collection and mode as canonical DTCG JSON + CSS custom properties; edit a hex value in code; push the delta back to Figma. Diff-aware merge produces exactly one API call per changed value, not a full collection rewrite. 103 tools total. [See what's new →](CHANGELOG.md#1270---2026-05-16)
|
|
12
12
|
|
|
13
13
|
## What is this?
|
|
14
14
|
|
|
15
15
|
Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
|
|
16
16
|
|
|
17
17
|
- **🎨 Design system extraction** - Pull variables, components, and styles
|
|
18
|
+
- **🔁 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.
|
|
18
19
|
- **📸 Visual debugging** - Take screenshots for context
|
|
19
20
|
- **✏️ Design creation** - Create UI components, frames, and layouts directly in Figma
|
|
20
21
|
- **🔧 Variable management** - Create, update, rename, and delete design tokens
|
|
22
|
+
- **🕰 Version history & time-series awareness** - List versions, diff snapshots, generate markdown changelogs, trace property/variant introduction via binary-search blame
|
|
21
23
|
- **⚡ Real-time monitoring** - Watch console logs from the Desktop Bridge plugin
|
|
22
24
|
- **📌 FigJam boards** - Create stickies, flowcharts, tables, and code blocks on collaborative boards
|
|
25
|
+
- **🎞️ Slides presentations** - Build and manage Figma Slides decks programmatically
|
|
23
26
|
- **♿ Accessibility scanning** - 14 WCAG design checks with conformance level tagging, component scorecards, axe-core code scanning, design-to-code parity
|
|
27
|
+
- **🛡 Cross-MCP identity** - Every tool response carries `_mcp: "figma-console-mcp"` and errors are prefixed `[figma-console-mcp]` so attribution stays unambiguous in agents running multiple Figma MCPs
|
|
24
28
|
- **☁️ Cloud Write Relay** - Web AI clients (Claude.ai, v0, Replit) can design in Figma via cloud pairing
|
|
25
29
|
- **🔄 Four ways to connect** - Remote SSE, Cloud Mode, NPX, or Local Git
|
|
26
30
|
|
|
@@ -51,9 +55,9 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
|
|
|
51
55
|
| Real-time monitoring (console, selection) | ✅ | ❌ | ❌ |
|
|
52
56
|
| Desktop Bridge plugin | ✅ | ✅ | ❌ |
|
|
53
57
|
| Requires Node.js | Yes | **No** | No |
|
|
54
|
-
| **Total tools available** | **
|
|
58
|
+
| **Total tools available** | **103** | **93** | **9** |
|
|
55
59
|
|
|
56
|
-
> **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
|
|
60
|
+
> **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.
|
|
57
61
|
|
|
58
62
|
---
|
|
59
63
|
|
|
@@ -61,7 +65,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
|
|
|
61
65
|
|
|
62
66
|
**Best for:** Designers who want full AI-assisted design capabilities.
|
|
63
67
|
|
|
64
|
-
**What you get:** All
|
|
68
|
+
**What you get:** All 103 tools including design creation, variable management, and component instantiation.
|
|
65
69
|
|
|
66
70
|
#### Prerequisites
|
|
67
71
|
|
|
@@ -128,9 +132,11 @@ If you're not sure where to put the JSON configuration above, here's where each
|
|
|
128
132
|
3. Select `~/.figma-console-mcp/plugin/manifest.json` (stable path, auto-created by the MCP server)
|
|
129
133
|
4. Run the plugin in your Figma file — it scans ports 9223–9232 and connects automatically to your running MCP server
|
|
130
134
|
|
|
131
|
-
> **Heads-up on plugin updates.** Figma caches plugin files (`code.js` and `ui.html`) at the application level.
|
|
135
|
+
> **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.
|
|
132
136
|
>
|
|
133
|
-
>
|
|
137
|
+
> **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).
|
|
138
|
+
>
|
|
139
|
+
> 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.
|
|
134
140
|
|
|
135
141
|
#### Step 4: Restart Your MCP Client
|
|
136
142
|
|
|
@@ -156,7 +162,7 @@ Create a simple frame with a blue background
|
|
|
156
162
|
|
|
157
163
|
**Best for:** Developers who want to modify source code or contribute to the project.
|
|
158
164
|
|
|
159
|
-
**What you get:** Same
|
|
165
|
+
**What you get:** Same 103 tools as NPX, plus full source code access.
|
|
160
166
|
|
|
161
167
|
#### Quick Setup
|
|
162
168
|
|
|
@@ -245,7 +251,7 @@ Ready for design creation? Follow the [NPX Setup](#-npx-setup-recommended) guide
|
|
|
245
251
|
|
|
246
252
|
**Best for:** Using Claude.ai, v0, Replit, or Lovable to create and modify Figma designs — no Node.js required.
|
|
247
253
|
|
|
248
|
-
**What you get:**
|
|
254
|
+
**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.
|
|
249
255
|
|
|
250
256
|
#### Prerequisites
|
|
251
257
|
|
|
@@ -302,7 +308,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
|
|
|
302
308
|
| Feature | NPX (Recommended) | Cloud Mode | Local Git | Remote SSE |
|
|
303
309
|
|---------|-------------------|------------|-----------|------------|
|
|
304
310
|
| **Setup time** | ~10 minutes | ~5 minutes | ~15 minutes | ~2 minutes |
|
|
305
|
-
| **Total tools** | **
|
|
311
|
+
| **Total tools** | **103** | **93** | **103** | **9** (read-only) |
|
|
306
312
|
| **Design creation** | ✅ | ✅ | ✅ | ❌ |
|
|
307
313
|
| **Variable management** | ✅ | ✅ | ✅ | ❌ |
|
|
308
314
|
| **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
|
|
@@ -317,7 +323,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
|
|
|
317
323
|
| **Automatic updates** | ✅ (`@latest`) | ✅ | Manual (`git pull`) | ✅ |
|
|
318
324
|
| **Source code access** | ❌ | ❌ | ✅ | ❌ |
|
|
319
325
|
|
|
320
|
-
> **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
|
|
326
|
+
> **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.
|
|
321
327
|
|
|
322
328
|
**📖 [Complete Feature Comparison](docs/mode-comparison.md)**
|
|
323
329
|
|
|
@@ -419,6 +425,10 @@ When you first use design system tools:
|
|
|
419
425
|
- `figma_check_design_parity` - Compare Figma component specs against code implementation, producing a scored diff report with actionable fix items
|
|
420
426
|
- `figma_generate_component_doc` - Generate platform-agnostic markdown documentation by merging Figma design data with code-side info
|
|
421
427
|
|
|
428
|
+
### 🔁 Token Sync (Local Mode + Cloud Mode)
|
|
429
|
+
- `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.
|
|
430
|
+
- `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).
|
|
431
|
+
|
|
422
432
|
### 🔧 Variable Management (Local Mode + Cloud Mode)
|
|
423
433
|
- `figma_create_variable_collection` - Create new variable collections with modes
|
|
424
434
|
- `figma_create_variable` - Create COLOR, FLOAT, STRING, or BOOLEAN variables
|
|
@@ -653,7 +663,7 @@ The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to t
|
|
|
653
663
|
- The MCP server communicates via **WebSocket** through the Desktop Bridge plugin
|
|
654
664
|
- The server tries port 9223 first, then automatically falls back through ports 9224–9232 if needed
|
|
655
665
|
- The plugin scans all ports in the range and connects to every active server it finds
|
|
656
|
-
- All
|
|
666
|
+
- All 103 tools work through the WebSocket transport
|
|
657
667
|
|
|
658
668
|
**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).
|
|
659
669
|
|
|
@@ -792,27 +802,28 @@ The architecture supports adding new apps with minimal boilerplate — each app
|
|
|
792
802
|
|
|
793
803
|
## 🛤️ Roadmap
|
|
794
804
|
|
|
795
|
-
**Current Status:** v1.
|
|
805
|
+
**Current Status:** v1.27.1 (Stable) - Production-ready with 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, **103 tools** (Local) / **95 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
|
|
796
806
|
|
|
797
807
|
**Recent Releases:**
|
|
798
|
-
- [x] **v1.
|
|
799
|
-
- [x] **v1.
|
|
800
|
-
- [x] **v1.
|
|
801
|
-
- [x] **v1.
|
|
802
|
-
- [x] **v1.
|
|
803
|
-
- [x] **v1.
|
|
804
|
-
- [x] **v1.
|
|
805
|
-
- [x] **v1.
|
|
806
|
-
- [x] **v1.
|
|
807
|
-
- [x] **v1.
|
|
808
|
-
- [x] **v1.
|
|
809
|
-
- [x] **v1.
|
|
808
|
+
- [x] **v1.27.0** - Bidirectional token sync: `figma_export_tokens` + `figma_import_tokens` replace Style Dictionary and Tokens Studio's export pipeline. Canonical DTCG JSON + CSS custom properties. Diff-aware merge with round-trip ID preservation via `$extensions["figma-console-mcp"]`. Apply phase pushes hex-value edits back to Figma via the plugin bridge. Verified end-to-end against 713-token + 280-token design systems.
|
|
809
|
+
- [x] **v1.26.0** - Internal cleanup + cross-MCP identity: Local-mode CDP/Puppeteer transport removed entirely (WebSocket-only). `figma_diagnose` tool for designer-readable health checks. Every response tagged `_mcp: "figma-console-mcp"`; errors prefixed `[figma-console-mcp]` so attribution is unambiguous when running multiple Figma MCPs. Plugin status pill now reads `Local · ready` / `Cloud · ready` / `Local + Cloud · ready`. Net diff: −7,299 lines, plugin re-import optional.
|
|
810
|
+
- [x] **v1.25.0** - Description + Dev Mode annotation tracking in `figma_diff_versions` via plugin session buffer. Description and annotation edits made during a session now appear in diff output (REST API doesn't return these — bridged through the plugin's `documentchange` listener).
|
|
811
|
+
- [x] **v1.24.0** - Honest scope coverage on version diffs. `scope_coverage` object surfaces what `figma_diff_versions` does and doesn't track; always-on coverage warnings prevent silent invisibility on token-value changes and component-instance placements.
|
|
812
|
+
- [x] **v1.23.0** - Version History & Time-Series Awareness: 6 new tools (list versions, snapshot any past version, diff two versions for component/binding deltas, generate markdown changelogs, trace property/variant introduction via binary-search blame walker). Author attribution flows from autosaves, not just labeled releases.
|
|
813
|
+
- [x] **v1.17.0** - Figma Slides support: 15 tools for managing presentations.
|
|
814
|
+
- [x] **v1.16.0** - FigJam support: 9 tools for creating and reading FigJam boards.
|
|
815
|
+
- [x] **v1.12.0** - Cloud Write Relay: web AI clients can create and modify Figma designs without Node.js.
|
|
816
|
+
- [x] **v1.11.0** - Complete CDP removal, improved multi-file active tracking with focus detection.
|
|
817
|
+
- [x] **v1.10.0** - Multi-instance support (dynamic port fallback 9223–9232, multi-connection plugin, instance discovery).
|
|
818
|
+
- [x] **v1.9.0** - Figma Comments tools, improved port conflict detection.
|
|
819
|
+
- [x] **v1.8.0** - WebSocket Bridge transport (CDP-free connectivity), real-time selection/document tracking.
|
|
820
|
+
- [x] **v1.7.0** - MCP Apps (Token Browser, Design System Dashboard), batch variable operations, design-code parity tools.
|
|
810
821
|
|
|
811
822
|
**Coming Next:**
|
|
823
|
+
- [ ] **Token sync Phase 2** - Tailwind v4 `@theme`, SCSS, TypeScript module, Style Dictionary v3 source format, `toCreate` apply orchestration, `toDelete` for `replace` strategy, cross-library variable resolution via `getVariableByIdAsync`.
|
|
812
824
|
- [ ] **Component template library** - Common UI pattern generation
|
|
813
825
|
- [ ] **Visual regression testing** - Screenshot diff capabilities
|
|
814
826
|
- [ ] **Design linting** - Automated compliance and accessibility checks
|
|
815
|
-
- [ ] **AI enhancements** - Intelligent component suggestions and auto-layout optimization
|
|
816
827
|
|
|
817
828
|
**📖 [Full Roadmap](docs/ROADMAP.md)**
|
|
818
829
|
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Alias reference resolution and validation.
|
|
3
|
+
*
|
|
4
|
+
* DTCG alias references look like `{color.primary}` or `{tier-1.color.blue.500}`.
|
|
5
|
+
* They can chain (an alias can reference another alias), but cycles are an
|
|
6
|
+
* error.
|
|
7
|
+
*
|
|
8
|
+
* This module:
|
|
9
|
+
* - Resolves an alias to its eventual literal value (for formatters that
|
|
10
|
+
* can't natively express references — CSS, SCSS, Tailwind).
|
|
11
|
+
* - Validates that every alias points to an existing token.
|
|
12
|
+
* - Detects cycles.
|
|
13
|
+
*/
|
|
14
|
+
import type { Token, TokenDocument, TokenValue } from "./types.js";
|
|
15
|
+
/**
|
|
16
|
+
* Build a lookup map from dot-path strings (e.g. "color.primary") to Token
|
|
17
|
+
* objects. Used as the index for resolveAliases().
|
|
18
|
+
*/
|
|
19
|
+
export declare function buildTokenIndex(doc: TokenDocument): Map<string, Token>;
|
|
20
|
+
/**
|
|
21
|
+
* Resolve a single alias reference. Returns the eventual literal value, or
|
|
22
|
+
* throws if the reference is unresolvable or cyclic.
|
|
23
|
+
*/
|
|
24
|
+
export declare function resolveReference(reference: string, mode: string, index: Map<string, Token>, seen?: Set<string>): TokenValue;
|
|
25
|
+
/**
|
|
26
|
+
* Validate every alias in the document. Returns a list of error messages —
|
|
27
|
+
* empty array means all aliases resolve cleanly.
|
|
28
|
+
*/
|
|
29
|
+
export declare function validateAliases(doc: TokenDocument): string[];
|
|
30
|
+
/**
|
|
31
|
+
* Format an alias reference for DTCG output. DTCG uses `{path.to.token}`
|
|
32
|
+
* syntax with curly braces.
|
|
33
|
+
*/
|
|
34
|
+
export declare function formatDtcgReference(referencePath: string[]): string;
|
|
35
|
+
/**
|
|
36
|
+
* Parse a DTCG alias string back into a path array. Returns null if the
|
|
37
|
+
* string isn't an alias reference.
|
|
38
|
+
*/
|
|
39
|
+
export declare function parseDtcgReference(s: string): string[] | null;
|
|
40
|
+
//# sourceMappingURL=alias-resolver.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
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"}
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Alias reference resolution and validation.
|
|
3
|
+
*
|
|
4
|
+
* DTCG alias references look like `{color.primary}` or `{tier-1.color.blue.500}`.
|
|
5
|
+
* They can chain (an alias can reference another alias), but cycles are an
|
|
6
|
+
* error.
|
|
7
|
+
*
|
|
8
|
+
* This module:
|
|
9
|
+
* - Resolves an alias to its eventual literal value (for formatters that
|
|
10
|
+
* can't natively express references — CSS, SCSS, Tailwind).
|
|
11
|
+
* - Validates that every alias points to an existing token.
|
|
12
|
+
* - Detects cycles.
|
|
13
|
+
*/
|
|
14
|
+
/**
|
|
15
|
+
* Build a lookup map from dot-path strings (e.g. "color.primary") to Token
|
|
16
|
+
* objects. Used as the index for resolveAliases().
|
|
17
|
+
*/
|
|
18
|
+
export function buildTokenIndex(doc) {
|
|
19
|
+
const index = new Map();
|
|
20
|
+
for (const set of doc.sets) {
|
|
21
|
+
for (const token of set.tokens) {
|
|
22
|
+
const key = token.path.join(".");
|
|
23
|
+
index.set(key, token);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
return index;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Resolve a single alias reference. Returns the eventual literal value, or
|
|
30
|
+
* throws if the reference is unresolvable or cyclic.
|
|
31
|
+
*/
|
|
32
|
+
export function resolveReference(reference, mode, index, seen = new Set()) {
|
|
33
|
+
// Strip the curly braces if present: "{color.primary}" → "color.primary"
|
|
34
|
+
const path = reference.replace(/^\{|\}$/g, "");
|
|
35
|
+
if (seen.has(path)) {
|
|
36
|
+
throw new Error(`[figma-console-mcp] Alias cycle detected: ${[...seen, path].join(" → ")}`);
|
|
37
|
+
}
|
|
38
|
+
seen.add(path);
|
|
39
|
+
const target = index.get(path);
|
|
40
|
+
if (!target) {
|
|
41
|
+
throw new Error(`[figma-console-mcp] Unresolvable alias reference: {${path}}`);
|
|
42
|
+
}
|
|
43
|
+
// Find the value for the requested mode; fall back to the only mode if
|
|
44
|
+
// there's just one (alias's target may be single-mode while the source
|
|
45
|
+
// is multi-mode, or vice versa).
|
|
46
|
+
const value = target.values[mode] ??
|
|
47
|
+
(Object.keys(target.values).length === 1
|
|
48
|
+
? Object.values(target.values)[0]
|
|
49
|
+
: undefined);
|
|
50
|
+
if (!value) {
|
|
51
|
+
throw new Error(`[figma-console-mcp] Alias {${path}} has no value for mode "${mode}"`);
|
|
52
|
+
}
|
|
53
|
+
// Chain: if the target's value is itself an alias, recurse.
|
|
54
|
+
if (value.reference) {
|
|
55
|
+
return resolveReference(value.reference, mode, index, seen);
|
|
56
|
+
}
|
|
57
|
+
return value;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Validate every alias in the document. Returns a list of error messages —
|
|
61
|
+
* empty array means all aliases resolve cleanly.
|
|
62
|
+
*/
|
|
63
|
+
export function validateAliases(doc) {
|
|
64
|
+
const index = buildTokenIndex(doc);
|
|
65
|
+
const errors = [];
|
|
66
|
+
for (const set of doc.sets) {
|
|
67
|
+
for (const token of set.tokens) {
|
|
68
|
+
for (const [mode, value] of Object.entries(token.values)) {
|
|
69
|
+
if (value.reference) {
|
|
70
|
+
try {
|
|
71
|
+
resolveReference(value.reference, mode, index);
|
|
72
|
+
}
|
|
73
|
+
catch (err) {
|
|
74
|
+
errors.push(`${token.path.join(".")} (mode "${mode}"): ${err instanceof Error ? err.message : String(err)}`);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
return errors;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Format an alias reference for DTCG output. DTCG uses `{path.to.token}`
|
|
84
|
+
* syntax with curly braces.
|
|
85
|
+
*/
|
|
86
|
+
export function formatDtcgReference(referencePath) {
|
|
87
|
+
return `{${referencePath.join(".")}}`;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Parse a DTCG alias string back into a path array. Returns null if the
|
|
91
|
+
* string isn't an alias reference.
|
|
92
|
+
*/
|
|
93
|
+
export function parseDtcgReference(s) {
|
|
94
|
+
const match = s.match(/^\{([^}]+)\}$/);
|
|
95
|
+
if (!match)
|
|
96
|
+
return null;
|
|
97
|
+
return match[1].split(".");
|
|
98
|
+
}
|
|
99
|
+
//# sourceMappingURL=alias-resolver.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"alias-resolver.js","sourceRoot":"","sources":["../../../src/core/tokens/alias-resolver.ts"],"names":[],"mappings":"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"}
|