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.
Files changed (134) hide show
  1. package/README.md +37 -26
  2. package/dist/core/tokens/alias-resolver.d.ts +40 -0
  3. package/dist/core/tokens/alias-resolver.d.ts.map +1 -0
  4. package/dist/core/tokens/alias-resolver.js +99 -0
  5. package/dist/core/tokens/alias-resolver.js.map +1 -0
  6. package/dist/core/tokens/config.d.ts +352 -0
  7. package/dist/core/tokens/config.d.ts.map +1 -0
  8. package/dist/core/tokens/config.js +285 -0
  9. package/dist/core/tokens/config.js.map +1 -0
  10. package/dist/core/tokens/figma-converter.d.ts +81 -0
  11. package/dist/core/tokens/figma-converter.d.ts.map +1 -0
  12. package/dist/core/tokens/figma-converter.js +196 -0
  13. package/dist/core/tokens/figma-converter.js.map +1 -0
  14. package/dist/core/tokens/formatters/css-vars.d.ts +24 -0
  15. package/dist/core/tokens/formatters/css-vars.d.ts.map +1 -0
  16. package/dist/core/tokens/formatters/css-vars.js +330 -0
  17. package/dist/core/tokens/formatters/css-vars.js.map +1 -0
  18. package/dist/core/tokens/formatters/dtcg.d.ts +28 -0
  19. package/dist/core/tokens/formatters/dtcg.d.ts.map +1 -0
  20. package/dist/core/tokens/formatters/dtcg.js +301 -0
  21. package/dist/core/tokens/formatters/dtcg.js.map +1 -0
  22. package/dist/core/tokens/formatters/index.d.ts +30 -0
  23. package/dist/core/tokens/formatters/index.d.ts.map +1 -0
  24. package/dist/core/tokens/formatters/index.js +46 -0
  25. package/dist/core/tokens/formatters/index.js.map +1 -0
  26. package/dist/core/tokens/formatters/json.d.ts +5 -0
  27. package/dist/core/tokens/formatters/json.d.ts.map +1 -0
  28. package/dist/core/tokens/formatters/json.js +8 -0
  29. package/dist/core/tokens/formatters/json.js.map +1 -0
  30. package/dist/core/tokens/formatters/less.d.ts +4 -0
  31. package/dist/core/tokens/formatters/less.d.ts.map +1 -0
  32. package/dist/core/tokens/formatters/less.js +5 -0
  33. package/dist/core/tokens/formatters/less.js.map +1 -0
  34. package/dist/core/tokens/formatters/scss.d.ts +4 -0
  35. package/dist/core/tokens/formatters/scss.d.ts.map +1 -0
  36. package/dist/core/tokens/formatters/scss.js +5 -0
  37. package/dist/core/tokens/formatters/scss.js.map +1 -0
  38. package/dist/core/tokens/formatters/stubs.d.ts +9 -0
  39. package/dist/core/tokens/formatters/stubs.d.ts.map +1 -0
  40. package/dist/core/tokens/formatters/stubs.js +12 -0
  41. package/dist/core/tokens/formatters/stubs.js.map +1 -0
  42. package/dist/core/tokens/formatters/style-dictionary-v3.d.ts +4 -0
  43. package/dist/core/tokens/formatters/style-dictionary-v3.d.ts.map +1 -0
  44. package/dist/core/tokens/formatters/style-dictionary-v3.js +5 -0
  45. package/dist/core/tokens/formatters/style-dictionary-v3.js.map +1 -0
  46. package/dist/core/tokens/formatters/tailwind-v3.d.ts +4 -0
  47. package/dist/core/tokens/formatters/tailwind-v3.d.ts.map +1 -0
  48. package/dist/core/tokens/formatters/tailwind-v3.js +5 -0
  49. package/dist/core/tokens/formatters/tailwind-v3.js.map +1 -0
  50. package/dist/core/tokens/formatters/tailwind-v4.d.ts +4 -0
  51. package/dist/core/tokens/formatters/tailwind-v4.d.ts.map +1 -0
  52. package/dist/core/tokens/formatters/tailwind-v4.js +5 -0
  53. package/dist/core/tokens/formatters/tailwind-v4.js.map +1 -0
  54. package/dist/core/tokens/formatters/tokens-studio.d.ts +4 -0
  55. package/dist/core/tokens/formatters/tokens-studio.d.ts.map +1 -0
  56. package/dist/core/tokens/formatters/tokens-studio.js +5 -0
  57. package/dist/core/tokens/formatters/tokens-studio.js.map +1 -0
  58. package/dist/core/tokens/formatters/ts-module.d.ts +4 -0
  59. package/dist/core/tokens/formatters/ts-module.d.ts.map +1 -0
  60. package/dist/core/tokens/formatters/ts-module.js +5 -0
  61. package/dist/core/tokens/formatters/ts-module.js.map +1 -0
  62. package/dist/core/tokens/index.d.ts +17 -0
  63. package/dist/core/tokens/index.d.ts.map +1 -0
  64. package/dist/core/tokens/index.js +16 -0
  65. package/dist/core/tokens/index.js.map +1 -0
  66. package/dist/core/tokens/parsers/css-vars.d.ts +3 -0
  67. package/dist/core/tokens/parsers/css-vars.d.ts.map +1 -0
  68. package/dist/core/tokens/parsers/css-vars.js +5 -0
  69. package/dist/core/tokens/parsers/css-vars.js.map +1 -0
  70. package/dist/core/tokens/parsers/dtcg.d.ts +21 -0
  71. package/dist/core/tokens/parsers/dtcg.d.ts.map +1 -0
  72. package/dist/core/tokens/parsers/dtcg.js +254 -0
  73. package/dist/core/tokens/parsers/dtcg.js.map +1 -0
  74. package/dist/core/tokens/parsers/index.d.ts +37 -0
  75. package/dist/core/tokens/parsers/index.d.ts.map +1 -0
  76. package/dist/core/tokens/parsers/index.js +139 -0
  77. package/dist/core/tokens/parsers/index.js.map +1 -0
  78. package/dist/core/tokens/parsers/json.d.ts +4 -0
  79. package/dist/core/tokens/parsers/json.d.ts.map +1 -0
  80. package/dist/core/tokens/parsers/json.js +8 -0
  81. package/dist/core/tokens/parsers/json.js.map +1 -0
  82. package/dist/core/tokens/parsers/scss.d.ts +3 -0
  83. package/dist/core/tokens/parsers/scss.d.ts.map +1 -0
  84. package/dist/core/tokens/parsers/scss.js +5 -0
  85. package/dist/core/tokens/parsers/scss.js.map +1 -0
  86. package/dist/core/tokens/parsers/stubs.d.ts +11 -0
  87. package/dist/core/tokens/parsers/stubs.d.ts.map +1 -0
  88. package/dist/core/tokens/parsers/stubs.js +14 -0
  89. package/dist/core/tokens/parsers/stubs.js.map +1 -0
  90. package/dist/core/tokens/parsers/style-dictionary-v3.d.ts +3 -0
  91. package/dist/core/tokens/parsers/style-dictionary-v3.d.ts.map +1 -0
  92. package/dist/core/tokens/parsers/style-dictionary-v3.js +5 -0
  93. package/dist/core/tokens/parsers/style-dictionary-v3.js.map +1 -0
  94. package/dist/core/tokens/parsers/tailwind-v3.d.ts +3 -0
  95. package/dist/core/tokens/parsers/tailwind-v3.d.ts.map +1 -0
  96. package/dist/core/tokens/parsers/tailwind-v3.js +5 -0
  97. package/dist/core/tokens/parsers/tailwind-v3.js.map +1 -0
  98. package/dist/core/tokens/parsers/tailwind-v4.d.ts +3 -0
  99. package/dist/core/tokens/parsers/tailwind-v4.d.ts.map +1 -0
  100. package/dist/core/tokens/parsers/tailwind-v4.js +5 -0
  101. package/dist/core/tokens/parsers/tailwind-v4.js.map +1 -0
  102. package/dist/core/tokens/parsers/tokens-studio.d.ts +3 -0
  103. package/dist/core/tokens/parsers/tokens-studio.d.ts.map +1 -0
  104. package/dist/core/tokens/parsers/tokens-studio.js +5 -0
  105. package/dist/core/tokens/parsers/tokens-studio.js.map +1 -0
  106. package/dist/core/tokens/schemas.d.ts +152 -0
  107. package/dist/core/tokens/schemas.d.ts.map +1 -0
  108. package/dist/core/tokens/schemas.js +149 -0
  109. package/dist/core/tokens/schemas.js.map +1 -0
  110. package/dist/core/tokens/transforms/color.d.ts +9 -0
  111. package/dist/core/tokens/transforms/color.d.ts.map +1 -0
  112. package/dist/core/tokens/transforms/color.js +13 -0
  113. package/dist/core/tokens/transforms/color.js.map +1 -0
  114. package/dist/core/tokens/transforms/index.d.ts +36 -0
  115. package/dist/core/tokens/transforms/index.d.ts.map +1 -0
  116. package/dist/core/tokens/transforms/index.js +30 -0
  117. package/dist/core/tokens/transforms/index.js.map +1 -0
  118. package/dist/core/tokens/transforms/size.d.ts +7 -0
  119. package/dist/core/tokens/transforms/size.d.ts.map +1 -0
  120. package/dist/core/tokens/transforms/size.js +8 -0
  121. package/dist/core/tokens/transforms/size.js.map +1 -0
  122. package/dist/core/tokens/types.d.ts +228 -0
  123. package/dist/core/tokens/types.d.ts.map +1 -0
  124. package/dist/core/tokens/types.js +19 -0
  125. package/dist/core/tokens/types.js.map +1 -0
  126. package/dist/core/tokens-tools.d.ts +42 -0
  127. package/dist/core/tokens-tools.d.ts.map +1 -0
  128. package/dist/core/tokens-tools.js +850 -0
  129. package/dist/core/tokens-tools.js.map +1 -0
  130. package/dist/local.d.ts.map +1 -1
  131. package/dist/local.js +14 -3
  132. package/dist/local.js.map +1 -1
  133. package/figma-desktop-bridge/code.js +1 -1
  134. package/package.json +1 -1
package/README.md CHANGED
@@ -6,21 +6,25 @@
6
6
  [![Documentation](https://img.shields.io/badge/docs-docs.figma--console--mcp.southleft.com-0D9488)](https://docs.figma-console-mcp.southleft.com)
7
7
  [![Sponsor](https://img.shields.io/badge/Sponsor-southleft-ea4aaa?logo=github-sponsors&logoColor=white)](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 **debugging**.
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
- > **🆕 Version History & Time-Series Awareness (v1.23.0):** Six new tools turn a Figma file from a static snapshot into a queryable history list versions, snapshot any past version, diff two versions for component/binding deltas, generate markdown changelogs ready for release notes, and trace exactly when (and by whom) a property or variant was introduced via a binary-search blame walker. Author attribution flows from autosaves, not just labeled releases. [See what's new →](CHANGELOG.md#1230---2026-05-09)
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** | **101** | **93** | **9** |
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 101 tools with real-time monitoring.
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 101 tools including design creation, variable management, and component instantiation.
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. When the MCP server publishes a plugin update — typically a `npm update` / new `npx` cache pull — re-import the manifest at `~/.figma-console-mcp/plugin/manifest.json` (Plugins Manage plugins re-import) to refresh the cached code. The stable path never changes, so re-importing is a quick one-click step.
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
- > The MCP server refreshes the files at the stable path on every startup; re-importing in Figma is what makes Figma pick them up.
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 101 tools as NPX, plus full source code access.
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:** 93 tools including full write access — design creation, variable management, component instantiation, and all REST API tools. Only real-time monitoring (console logs, selection tracking, document changes) requires Local Mode.
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** | **101** | **93** | **101** | **9** (read-only) |
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 101 tools.
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 101 tools work through the WebSocket transport
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.23.0 (Stable) - Production-ready with version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 101 tools, Comments API, and MCP Apps
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.17.0** - Figma Slides Support: 15 new tools for managing presentations slides, transitions, content, reordering, and navigation. Inspired by Toni Haidamous (PR #11).
799
- - [x] **v1.16.0** - FigJam Support: 9 new tools for creating and reading FigJam boards stickies, flowcharts, tables, code blocks, and connection graphs. Community-contributed by klgral and lukemoderwell.
800
- - [x] **v1.12.0** - Cloud Write Relay: web AI clients (Claude.ai, v0, Replit, Lovable) can create and modify Figma designs via cloud relay pairingno Node.js required
801
- - [x] **v1.11.2** - Screenshot fix: `figma_take_screenshot` works without explicit `nodeId` in WebSocket mode
802
- - [x] **v1.11.1** - Doc generator fixes: clean markdown tables, Storybook links, property metadata filtering
803
- - [x] **v1.11.0** - Complete CDP removal, improved multi-file active tracking with focus detection
804
- - [x] **v1.10.0** - Multi-instance support (dynamic port fallback 9223–9232, multi-connection plugin, instance discovery)
805
- - [x] **v1.9.0** - Figma Comments tools, improved port conflict detection
806
- - [x] **v1.8.0** - WebSocket Bridge transport (CDP-free connectivity), real-time selection/document tracking, `figma_get_selection` + `figma_get_design_changes` tools
807
- - [x] **v1.7.0** - MCP Apps (Token Browser, Design System Dashboard), batch variable operations, design-code parity tools
808
- - [x] **v1.5.0** - Node manipulation tools, component property management, component set arrangement
809
- - [x] **v1.3.0** - Design creation via `figma_execute`, variable CRUD operations
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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"}