@atelier-ui/create-workspace 0.4.1 → 0.4.3

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 (27) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/package.json +1 -1
  3. package/src/generators/preset/files/claude/skills/figma-workspace-architect/SKILL.md +194 -0
  4. package/src/generators/preset/files/claude/skills/figma-workspace-architect/assets/audit-report-template.md +181 -0
  5. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-checklist.md +462 -0
  6. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-verify-queries.md +414 -0
  7. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-from-code-contract.md +87 -0
  8. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-workflow.md +260 -0
  9. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-sync.md +218 -0
  10. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-verify.md +152 -0
  11. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/component-design.md +198 -0
  12. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/decision-heuristics.md +262 -0
  13. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/iconography.md +150 -0
  14. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-generation.md +433 -0
  15. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-payload.md +490 -0
  16. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/migration-playbook.md +182 -0
  17. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/naming-and-file-structure.md +161 -0
  18. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/plugin-api-gotchas.md +79 -0
  19. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/scaffold-payload.md +279 -0
  20. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/sync-workflow.md +98 -0
  21. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/token-architecture.md +177 -0
  22. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/tool-map.md +398 -0
  23. package/src/generators/preset/files/claude/skills/uianatomy-mcp/SKILL.md +160 -0
  24. package/src/generators/preset/files/tools/design-contracts/bin/check-contracts.mjs +7 -2
  25. package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
  26. package/src/generators/preset/preset.js +52 -4
  27. package/src/generators/preset/preset.js.map +1 -1
@@ -0,0 +1,177 @@
1
+ # Token architecture
2
+
3
+ The shape of the Variables system inside a Figma file is the single biggest predictor of whether the rest of the system holds up. Get this wrong and every Component built on top inherits the mess.
4
+
5
+ ## The three-tier model
6
+
7
+ Use three Collections, one per tier. The tiers are named here as they typically appear; exact naming should match the codebase if the team has a convention there.
8
+
9
+ ### Primitive (a.k.a. Global, Reference)
10
+
11
+ What it is: every raw value that exists in the design language. Color ramps, the spacing scale, the radius scale, the shadow values, the type scale.
12
+
13
+ What it is **not**: anything semantic. Nothing in this collection should reference what it's _for_.
14
+
15
+ | Looks like | Don't do |
16
+ | ---------------------------- | ----------------------- |
17
+ | `color/blue/500` = `#2563EB` | `color/primary/default` |
18
+ | `space/4` = `16` | `space/card-padding` |
19
+ | `radius/md` = `8` | `radius/button` |
20
+ | `font-size/300` = `16` | `font-size/body` |
21
+
22
+ Modes: usually **none**. Primitives are the same regardless of theme — that's why they're primitives.
23
+
24
+ Scope: each variable narrowly scoped to its data type's natural pickers (e.g. color primitives → `FRAME_FILL`, `SHAPE_FILL`, `TEXT_FILL`, `STROKE_COLOR`).
25
+
26
+ ### Semantic (a.k.a. Tokens, Aliases)
27
+
28
+ What it is: every choice the design language has made about _where_ a primitive applies. These variables almost never hold raw values — they alias Primitives.
29
+
30
+ | Looks like | What it aliases (Light / Dark) |
31
+ | ------------------------------------------- | -------------------------------- |
32
+ | `color/text/primary` → `color/neutral/900` | Light / `color/neutral/100` Dark |
33
+ | `color/surface/raised` → `color/neutral/0` | Light / `color/neutral/800` Dark |
34
+ | `color/border/subtle` → `color/neutral/200` | Light / `color/neutral/700` Dark |
35
+ | `space/inline/md` → `space/4` | (no mode change) |
36
+
37
+ Modes: **this is where Light/Dark/Brand modes live.** The Primitive collection stays single-mode; the Semantic collection swaps which Primitive each token resolves to per mode.
38
+
39
+ Scope: tighter than Primitives. `color/text/*` should scope to `TEXT_FILL` only. `color/border/*` to `STROKE_COLOR`. `color/surface/*` to `FRAME_FILL` and `SHAPE_FILL`. This is what makes pickers usable.
40
+
41
+ ### Component (optional)
42
+
43
+ What it is: tokens specific to a single component, e.g. `button/primary/background-default`, `card/padding-x`. They alias Semantics.
44
+
45
+ When to use: only when a component has multiple state-driven values that are easier to maintain centrally than as repeated overrides. Most teams don't need this layer in Figma at all and keep it on the code side. **If unsure, skip it** — added layers cost discoverability.
46
+
47
+ Modes: rarely. State (hover, active) is usually a Variant property, not a mode.
48
+
49
+ ## Variable types beyond color
50
+
51
+ The architecture above generalizes across all four Variable types. Use the right type for each value — not everything is a color.
52
+
53
+ | Type | Use for | Scope examples |
54
+ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
55
+ | **COLOR** | Fills, strokes, text colors, background surfaces. | `FRAME_FILL`, `TEXT_FILL`, `STROKE_COLOR` |
56
+ | **FLOAT** (Number) | Spacing, radius, stroke width, font-size, line-height, opacity, fixed widths/heights. | `GAP`, `CORNER_RADIUS`, `STROKE_FLOAT`, `FONT_SIZE`, `LINE_HEIGHT`, `OPACITY`, `WIDTH_HEIGHT` |
57
+ | **STRING** | Font family, font style, locale-specific labels, marketing copy that needs to vary per mode/brand. | `FONT_FAMILY`, `FONT_STYLE` |
58
+ | **BOOLEAN** | System flags consumed by component visibility-toggles or by code (`feature/reduce-motion`, `density/compact`). Not bound into design properties via scopes. | (no scope — boolean variables are exempt from the picker model) |
59
+
60
+ A workspace that only uses COLOR variables is incomplete. Spacing, radius, and typography belong on FLOAT and STRING variables; a hardcoded `16px` or `'Inter'` in a component is the same drift problem as a hardcoded `#007070`.
61
+
62
+ **Boolean-variable note.** `BOOLEAN` variables are never bound through Variable Scopes — they're consumed via component property logic or read by code. They're exempt from the TA4 scope audit (the audit-checklist explicitly filters `resolvedType === 'BOOLEAN'` before counting `ALL_SCOPES` offenders).
63
+
64
+ ### Variable Expressions — prototype-time only
65
+
66
+ Figma supports expressions inside Variable values for **prototyping interactions** — they evaluate at runtime when a prototype plays. Architecturally they are **not** a substitute for aliases:
67
+
68
+ - An expression in a static design context will not resolve — the rendered value is whatever the expression evaluates to in the editor, not a live computation.
69
+ - Code-gen tools and exporters read static values, not expressions; an expression-driven Variable looks like a constant when read by `figma_get_variables`.
70
+
71
+ Use expressions if you're authoring prototypes. Use `{ alias: '...' }` when one Variable should resolve through another in the static design surface.
72
+
73
+ ## Modes — when to use one
74
+
75
+ A Mode is appropriate when **the same semantic token resolves to a different value in a different context**. The classic uses:
76
+
77
+ - **Light / Dark** — the canonical case
78
+ - **Brand A / Brand B** — multi-tenant systems
79
+ - **Density: Comfortable / Compact** — sometimes
80
+ - **Locale: en / de / ja** — only for string variables, when text length needs different sizes
81
+
82
+ A Mode is **not** appropriate for:
83
+
84
+ - States (hover, active, focused) — those are Variant properties on the component
85
+ - Different sizes of the same component — those are Variant properties (`Size: sm/md/lg`)
86
+ - Sub-brands that are actually different design languages — that's a separate Library, not a mode
87
+
88
+ Adding a Mode duplicates every value in the collection for that mode, so adding modes carelessly creates maintenance debt fast. Add modes only at the Semantic tier — Primitive modes mean someone misunderstood the model.
89
+
90
+ ### Mode limits per plan tier
91
+
92
+ Figma caps the number of Modes per Collection by plan. Check the team's tier **before** proposing a multi-axis Mode topology — if Theme × Density × Brand crosses the ceiling, the design has to collapse modes (combine Density into the Brand axis) or split into separate library files.
93
+
94
+ | Plan | Modes / Collection |
95
+ | ---------- | --------------------- |
96
+ | Free | 1 (no theming) |
97
+ | Pro | 4 |
98
+ | Org | 10 |
99
+ | Enterprise | 40 (post-Schema 2025) |
100
+
101
+ Audit signal:
102
+
103
+ - Mode count **at or above** the tier ceiling → Blocker. Cannot add another mode without paid upgrade or a structural collapse.
104
+ - Mode count = ceiling − 1 → Warning. One more axis exhausts the budget.
105
+ - Plan unknown but designs assume ≥4 modes → ask the user; default planning assumption is Pro (4).
106
+
107
+ The cheapest fix when a design exceeds the budget is usually to lift one axis (e.g. Brand) into a _separate library file_ — Brand A and Brand B each consume the shared Foundations library and override only the brand-specific Semantic values. Each library still has its own mode budget for Theme + Density.
108
+
109
+ ## Variable Scopes — the silent killer
110
+
111
+ Default scope is `ALL_SCOPES`. That means a `color/text/primary` variable shows up in the picker for fills, borders, and every other color-accepting property. The picker becomes a wall of irrelevant suggestions and designers stop using Variables.
112
+
113
+ Set scopes deliberately for every Variable. Scopes are set via `figma_execute` calling `variable.scopes = [...]` on the Plugin API.
114
+
115
+ | Variable purpose | Scopes |
116
+ | ---------------------------------- | --------------------------------------------------- |
117
+ | Background / surface color | `FRAME_FILL`, `SHAPE_FILL` |
118
+ | Text color | `TEXT_FILL` |
119
+ | Border color | `STROKE_COLOR` |
120
+ | Icon color (if separate from text) | `SHAPE_FILL` (or a custom Effect Style on icons) |
121
+ | Spacing inside a layout | `GAP` |
122
+ | Padding | `GAP` (Auto Layout uses `GAP` for padding too) |
123
+ | Width / height fixed | `WIDTH_HEIGHT` |
124
+ | Border radius | `CORNER_RADIUS` |
125
+ | Stroke width | `STROKE_FLOAT` |
126
+ | Opacity | `OPACITY` |
127
+ | Font size | `FONT_SIZE` |
128
+ | Font weight (numeric) | `FONT_WEIGHT` |
129
+ | Line height | `LINE_HEIGHT` |
130
+ | Letter spacing | `LETTER_SPACING` |
131
+ | Font family (string) | `FONT_FAMILY` |
132
+ | Font style (string) | `FONT_STYLE` |
133
+ | Visibility toggle (boolean) | (booleans don't need scopes — they go on the layer) |
134
+
135
+ Audit signal: a Primitive that's only ever consumed via a Semantic alias should still be scoped — because the alias inherits the Primitive's scope intersected with its own. A wide-scoped Primitive widens the alias unintentionally.
136
+
137
+ ### `codeSyntax` — the name the agent reads out
138
+
139
+ Every Variable carries an optional `codeSyntax` map (`WEB`, `ANDROID`, `iOS`). When `WEB` is set — `--ui-color-primary`, `var(--ui-spacing-4)` — an MCP read of a bound node returns the code token, and a coding agent writes `var(--ui-color-primary)`; when it is unset, the same read returns the Figma path or a resolved hex, and the agent writes `#006470`. Practitioners report this as the single most common reason "the agent used raw values although the file is fully tokenised". Set it from the code side in the same pass that creates or syncs the Variables (`figma_execute`: `variable.setVariableCodeSyntax('WEB', '--ui-…')`; `figma_import_tokens` round-trips it through `$extensions`), and treat a semantic Variable without `codeSyntax.WEB` as a TA4-class finding: the token exists, but not for the reader that matters.
140
+
141
+ ## Naming
142
+
143
+ The naming convention should match the codebase as closely as possible. Variable paths use `/` as the segment separator (Figma renders it as a folder hierarchy in the picker).
144
+
145
+ **Recommended structure:**
146
+
147
+ ```
148
+ {category}/{purpose}/{variant}/{state?}
149
+ ```
150
+
151
+ Examples:
152
+
153
+ - `color/text/primary` → `color.text.primary` in CSS-like
154
+ - `color/text/primary/disabled` → state suffix when needed
155
+ - `space/inline/md` → inline spacing, medium
156
+ - `space/stack/lg` → stack (vertical) spacing, large
157
+ - `radius/control/md` → radius applied to controls, medium
158
+
159
+ **Avoid:**
160
+
161
+ - T-shirt sizes when the codebase uses numbers (`sm/md/lg` vs. `2/4/8`) — pick one, stay consistent
162
+ - Color names at the Semantic tier (`color/blue/primary` — the whole point of Semantics is that the color name is hidden)
163
+ - Plurals (`colors/text` rather than `color/text`) — keep singular, it reads better in the picker
164
+ - Underscores in user-facing variable names (codebase compatibility) — the `_`/`.` prefix is reserved for _unpublished_ component names, not variables
165
+
166
+ ## Anti-patterns checklist
167
+
168
+ If you see any of these in an existing file, flag them in the audit:
169
+
170
+ - **Single mega-collection** containing primitives, semantics, and components mixed together. Verdict: split. Critical severity.
171
+ - **Primitives have modes** (e.g. `color/blue/500` has a different value in Dark mode). Verdict: the team is using primitives as semantics. The semantic layer is missing. Critical.
172
+ - **No semantic layer at all** — components reference Primitives directly. Verdict: dark mode/theming is impossible without rebuilding every component. Blocker if dark mode is on the roadmap, Warning otherwise.
173
+ - **`ALL_SCOPES` everywhere** — inferred from the picker showing color tokens for spacing pickers, etc. Verdict: scope every variable. Critical.
174
+ - **Hex values inside Semantic variables** — semantics should always alias Primitives, never hold raw values. If a semantic has a raw hex, the corresponding primitive is missing. Warning.
175
+ - **A Semantic variable that points to a different Semantic variable** that points to a Primitive — long alias chains are debugging hell. One alias hop is correct; two means a layer was misused. Warning.
176
+ - **Mode names like "Theme 1", "Theme 2"** — modes that don't carry meaning. Rename to "Light"/"Dark"/"Brand-A". Suggestion.
177
+ - **Color tokens named for what they look like** at the Semantic tier (`color/sky-blue/primary`). The Semantic name should describe purpose, not appearance. Warning.
@@ -0,0 +1,398 @@
1
+ # figma-console-mcp tool map
2
+
3
+ Tool names in this map are the `figma-console` MCP server's own names. In a client with
4
+ more than one Figma-related MCP server connected, qualify each call as `figma-console:<tool>`
5
+ (e.g. `figma-console:figma_get_variables`) so the right server handles it.
6
+
7
+ A purpose-organized view of the figma-console-mcp tool surface, with the rule of thumb for when to reach for each one. Source: [southleft/figma-console-mcp](https://github.com/southleft/figma-console-mcp).
8
+
9
+ > **Mode awareness.** Write tools (anything that creates or mutates Figma content) only work in **Local Mode** (NPX or Local Git installation) with the **Desktop Bridge plugin** running in Figma Desktop. Remote SSE is read-only and exposes ~21 tools. If a write tool returns "not available" or similar, the user is on Remote SSE and must switch to Local Mode for build operations. Audits work in either mode.
10
+
11
+ ## Read & extract — always available
12
+
13
+ Use these for **discovery** (before any build) and as **inputs to audits**.
14
+
15
+ | Tool | Use when… |
16
+ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
+ | `figma_get_status` | Sanity check — is the bridge connected, which transport, which file? |
18
+ | `figma_get_file_data` | Top-level structure of the file: pages, frames, components, hierarchy. Big payload — use early. |
19
+ | `figma_get_file_for_plugin` | Same data, optimized for plugin-side processing. Prefer when feeding into `figma_execute`. |
20
+ | `figma_get_design_system_kit` | One-call snapshot of tokens + components + styles + visualSpec. **Prefer this** over orchestrating `figma_get_variables` + `figma_get_styles` + several `figma_get_component` calls when the goal is a complete read of the design system. |
21
+ | `figma_get_design_system_summary` | Counts only — components, collections, styles, pages. Cheap pre-flight before deciding which deeper read to run. |
22
+ | `figma_get_variables` | Extract all Variables and Collections, including Modes. Works without Enterprise via the Desktop Bridge — that's the main reason this MCP exists. |
23
+ | `figma_get_styles` | Color, text, and effect Styles (the legacy layer — most modern setups should be on Variables). |
24
+ | `figma_get_text_styles` | Local text styles with IDs, font, size, line-height. Use when audit needs typography coverage and `figma_get_styles` returns the legacy bundle. |
25
+ | `figma_get_component` | One component's data. Two output shapes: `metadata` (descriptive) or `reconstruction` (programmatic spec for re-creating it). |
26
+ | `figma_get_component_for_development` | Component data + rendered image, for handoff or visual diff. |
27
+ | `figma_get_component_for_development_deep` | Unlimited-depth tree, resolved Variable / token names per node, includes reactions. Use for compound components where the standard depth-limited read drops nested context. |
28
+ | `figma_get_component_details` | Full metadata by `componentKey` — variant property definitions, descriptions, instance counts. The right read when you have a key from `figma_search_components` but no node ID. |
29
+ | `figma_get_component_image` | Just the image. Cheap. Useful for spot-checks during a build. |
30
+ | `figma_get_library_components` | Browse another file's published library. Cross-file discovery — the Tokens-library + Component-library pattern needs this. |
31
+ | `figma_get_library_component_by_key` | Resolve a library component's props, variants, and visual spec from just its `componentKey` — no source file URL needed. Auto-downgrades to a summary and strips specs over 500KB. (REST) |
32
+ | `figma_get_library_variables` | Inventory Variables published by a subscribed team library, scoped by `libraryName` / `collectionName`. (Bridge) |
33
+ | `figma_import_library_variable` | Import one library Variable into the current file by `variableKey`. Idempotent — safe to call again on the same key. (Bridge) |
34
+ | `figma_search_components` | Find components by name in current file or a linked library. Discovery before re-creating: search-then-instantiate beats build-from-scratch when the component already exists. |
35
+ | `figma_take_screenshot` | Full canvas screenshot. Standard post-write check — but note it goes through the REST API and **may be cache-stale immediately after a write**. Prefer `figma_capture_screenshot` (Validate section) for the first screenshot after a write. |
36
+ | `figma_navigate` | Move the canvas to a node / page. Use to disambiguate "this component" without asking the user. |
37
+ | `figma_get_selection` | What is currently selected in Figma. Lets the agent act on the user's literal pick instead of guessing. |
38
+ | `figma_list_open_files` | Multi-file workspaces — which Figma files are open in Desktop. Needed before `figma_navigate` across files. |
39
+
40
+ **Discovery pattern.** Before a build, this is the typical order: `figma_get_status` → `figma_get_file_data` (or `figma_get_design_system_kit` for a one-call full snapshot) → (if Variables matter) `figma_get_variables` → (if components matter) `figma_search_components` then `figma_get_component` on the relevant ones.
41
+
42
+ ### Session & multi-file
43
+
44
+ | Tool | Use when… |
45
+ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46
+ | `figma_diagnose` | Plain-language health check when the Bridge misbehaves — also disambiguates this server from other Figma-related MCP servers the user may have installed (e.g. the official `figma-mcp`). |
47
+ | `figma_execute_across_files` | Run the same Plugin API JS across every connected file in parallel. Local Mode only — the multi-file counterpart to `figma_execute`. (Bridge) |
48
+
49
+ `figma_navigate` (above) also accepts `lock: true`, which pins the active file target so a Bridge reconnect or the human clicking elsewhere in Figma can't silently redirect subsequent calls.
50
+
51
+ ## Create & manage Variables / Tokens — Local Mode only
52
+
53
+ Variable management is the most common write workflow. Always check existing Collections via `figma_get_variables` before creating.
54
+
55
+ | Tool | Use when… |
56
+ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
57
+ | `figma_setup_design_tokens` | **Bootstrapping a new token system from scratch** — creates collection + modes + variables in one atomic call. By far the fastest path for a green-field design system. |
58
+ | `figma_create_variable_collection` | Adding a single new Collection to an existing setup (e.g. introducing a `Layout` collection alongside `Color`). |
59
+ | `figma_create_variable` | One-off variable. Avoid in loops — use `figma_batch_create_variables` instead. |
60
+ | `figma_batch_create_variables` | Up to 100 variables in one call. **10–50× faster than looping.** Use whenever creating ≥3 variables. |
61
+ | `figma_update_variable` | Change a variable's value in a specific mode. |
62
+ | `figma_batch_update_variables` | Up to 100 value updates in one call. Use for theme migrations, semantic re-aliasing, etc. |
63
+ | `figma_rename_variable` | Rename while preserving aliases and usages. Safer than delete + recreate. |
64
+ | `figma_delete_variable` | Remove a single variable. Surfaces in the file as broken aliases — confirm with the user first. |
65
+ | `figma_delete_variable_collection` | Removes the collection AND all its variables. **Destructive — confirm explicitly.** |
66
+ | `figma_add_mode` | Add a Mode to an existing collection (e.g. "Dark", "Mobile", "Brand-B"). |
67
+ | `figma_rename_mode` | Renames preserve all variable values in that mode. |
68
+
69
+ **Important — Variable Scopes.** None of these tools expose Scopes directly through their named API. Scopes (`FRAME_FILL`, `TEXT_FILL`, `GAP`, `STROKE_COLOR`, `WIDTH_HEIGHT`, etc.) are set via `figma_execute` running Plugin API code on the variable after creation. Default `ALL_SCOPES` makes Variables show up in every property picker, which destroys the user experience. See `token-architecture.md` for the scope-by-purpose table.
70
+
71
+ ## Token import / export
72
+
73
+ Round-trips Variables with external token tooling — the equivalent of Style Dictionary / Tokens Studio without leaving the MCP surface.
74
+
75
+ | Tool | Use when… |
76
+ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77
+ | `figma_export_tokens` | Write Variables out to DTCG, CSS, Tailwind, SCSS, TS, or JSON files (10 formats total), with a merge-or-replace strategy. (Bridge) |
78
+ | `figma_import_tokens` | Diff-and-apply token files back into Variables, alias-aware. **Only DTCG is fully round-trip safe** — Tokens Studio JSON, raw CSS vars, Tailwind v4, SCSS, and Style Dictionary v3 as inputs are scaffolded but return `NotImplementedError`; convert to DTCG first. A `replace` strategy can delete existing variables. (Bridge) |
79
+ | `figma_get_token_values` | Resolved token values after a `figma_get_design_system_summary` call — cheaper than re-reading the full Variables set for a values-only need. |
80
+ | `figma_browse_tokens` | Interactive token browser for a human to explore Variables across modes. MCP App — needs `ENABLE_MCP_APPS=true` and client support for the MCP Apps protocol. |
81
+ | `token_browser_refresh` | Refresh the Token Browser app's data after the underlying Variables changed. MCP App — same `ENABLE_MCP_APPS` requirement as `figma_browse_tokens`. |
82
+
83
+ ## Targeted node writes — Local Mode only
84
+
85
+ These tools mutate one specific property on one node. They are **safer** than `figma_execute` (typed API, validated input) and **faster** to write because there is no Plugin API boilerplate. Reach for them first; reserve `figma_execute` for compound mutations.
86
+
87
+ | Tool | Use when… |
88
+ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
89
+ | `figma_clone_node` | Duplicate a node with all its bindings preserved. |
90
+ | `figma_create_child` | Add a child of a known type (FRAME / TEXT / RECTANGLE / etc.) to a parent. |
91
+ | `figma_delete_node` | Remove one node. Confirm with the user if it might be referenced. |
92
+ | `figma_move_node` | Reposition by `x`/`y` or reparent. |
93
+ | `figma_rename_node` | Single-property rename without writing a Plugin API payload. |
94
+ | `figma_resize_node` | Set width / height. For Auto-Layout containers this also sets `layoutSizing*`. |
95
+ | `figma_set_fills` | Bind a fill or set a raw paint. Validates the paint shape. |
96
+ | `figma_set_strokes` | Same, for strokes. |
97
+ | `figma_set_image_fill` | Image-fill specifically — wraps the imageHash + scaling-mode dance. |
98
+ | `figma_set_text` | Replace the characters of a TEXT node. **Note:** for instances, use `figma_set_instance_properties` instead — bare-text edits on instance children fail silently. |
99
+
100
+ **Rule of thumb.** Single-property mutation → targeted tool. Multiple mutations on the same node, or any composition / branching logic → one `figma_execute` payload. Don't loop targeted tools when the same script could do the work atomically.
101
+
102
+ ## Create & manage Components — Local Mode only
103
+
104
+ Components and frames are created via the general-purpose `figma_execute`. There are a few specialized helpers for common patterns.
105
+
106
+ | Tool | Use when… |
107
+ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
108
+ | `figma_execute` | The power tool. Any Plugin API JS — create frames, components, set Auto Layout, bind variables, set Variant Properties. Most compound component work goes through this. |
109
+ | `figma_create_component_set` | Build a variant Component Set from a base component + property definitions, or from a set of existing components, in one call — the programmatic alternative to hand-arranging frames. Hard-capped at 100 variants (timeout auto-scales ~1.2s/variant, 30s floor/2min cap); split any matrix above ~40 variants into multiple calls. (Bridge) |
110
+ | `figma_arrange_component_set` | Take a flat group of variant frames and arrange them into a proper Component Set with the native purple dashed border, row labels, and column headers. **Always use this instead of trying to draw the container manually in `figma_execute`.** Triggers on phrases like "arrange these variants" or "organize as component set". |
111
+ | `figma_set_description` | Set markdown-formatted descriptions on Components, Component Sets, and Styles. Surfaces in the asset panel tooltip and in Dev Mode. **Set this for every component you create** — undocumented components are invisible. |
112
+ | `figma_instantiate_component` | Place an instance from a local or library component via `componentKey`. Pair with `figma_search_components` for the discovery → place flow. |
113
+ | `figma_set_instance_properties` | Set TEXT / BOOL / INSTANCE_SWAP / VARIANT properties on an instance. Handles the `#nodeId`-suffix that property keys carry. **Use this for text edits on instances** — `figma_set_text` on an instance child fails silently. |
114
+ | `figma_add_component_property` | Define a new Component Property (Boolean / Text / Instance Swap) on a Component or Component Set. Typed API; prefer over hand-rolling `componentPropertyDefinitions` in `figma_execute`. |
115
+ | `figma_edit_component_property` | Rename or change the default of an existing Component Property. Atomic; preserves bindings. |
116
+ | `figma_delete_component_property` | Remove a Component Property. Breaking — confirm with user, follow the migration coordination protocol if instances exist. |
117
+
118
+ **Pattern: build → arrange → describe → annotate → mark-ready.** Build the variant frames with `figma_execute`, arrange them into a Component Set with `figma_arrange_component_set`, attach a description with `figma_set_description`, attach Dev-Mode annotations with `figma_set_annotations` for non-obvious behavior, then mark the containing Section/Frame Ready-for-dev. Skipping any step leaves the component half-finished. See `build-workflow.md` Phases 6–8.
119
+
120
+ **Properties: high-level CRUD vs. `figma_execute`.** Prefer `figma_add_component_property` / `figma_edit_component_property` / `figma_delete_component_property` over manipulating `componentPropertyDefinitions` directly. The high-level tools are typed, atomic, and easier to read in chat. Reach for `figma_execute` only when defining a property must happen alongside other mutations in one atomic step (e.g. "add the property AND bind every variant's fill in one go").
121
+
122
+ **Gotcha: TEXT-property `defaultValue` coercion.** `figma_add_component_property` with `type: 'TEXT'` rejects numeric-looking string defaults — passing `defaultValue: '3'` errors with `Property "node.addComponentProperty.defaultValue" failed validation: Expected one of the following, but none matched: Expected boolean, received number; Expected string, received number; Expected object, received number`. The validator coerces the digit-only string to a number before type-checking. Workaround: define the property via `figma_execute` directly — `node.addComponentProperty('max', 'TEXT', '3')` accepts the string default. Same pattern for any TEXT default that parses cleanly as a number (`'0'`, `'42'`, `'-1'`). Non-numeric strings (`'placeholder'`, `'3 items'`) work fine through the typed CRUD tool.
123
+
124
+ **Gotcha: Auto-Layout-with-absolute-children inflates the parent.** When retrofitting Auto Layout onto an existing fixed-frame composition (the standard CD9 fix path), the obvious sequence is:
125
+
126
+ ```js
127
+ // WRONG order — frame width inflates to sum of children
128
+ frame.layoutMode = 'HORIZONTAL';
129
+ for (const c of frame.children) c.layoutPositioning = 'ABSOLUTE';
130
+ ```
131
+
132
+ Setting `layoutMode = 'HORIZONTAL'` first triggers Auto Layout to flow the children horizontally — frame width grows to `sum(child.width) + spacing`. By the time the loop sets each child to `ABSOLUTE`, the frame has already been resized. A 1080-wide composition with eight children commonly inflates to 6000–10000 pixels wide.
133
+
134
+ **Correct order — flip absolute first, then enable Auto Layout:**
135
+
136
+ ```js
137
+ // Snapshot original positions because flipping ABSOLUTE briefly clears them
138
+ const positions = frame.children.map((c) => ({ id: c.id, x: c.x, y: c.y }));
139
+ frame.layoutMode = 'HORIZONTAL';
140
+ for (const c of frame.children) c.layoutPositioning = 'ABSOLUTE';
141
+ // Restore positions and explicitly resize the frame back
142
+ for (const p of positions) {
143
+ const child = await figma.getNodeByIdAsync(p.id);
144
+ if (child) {
145
+ child.x = p.x;
146
+ child.y = p.y;
147
+ }
148
+ }
149
+ frame.resize(originalWidth, originalHeight); // critical — Auto Layout still mutated bounds
150
+ ```
151
+
152
+ The frame.resize() at the end is non-optional — even with ABSOLUTE children, the bounds set during the brief Auto-Layout pass persist. If you don't have the original size on hand, you can fall back to `Math.max(maxRight, maxBottom)` over the children, but that misses frames whose visible bounds come from their own fills (Avatar shape, Skeleton placeholder) and not from any child. For those, hardcode the canonical size from the variant name (`size=md` → 40, etc).
153
+
154
+ This is the most common single source of corrupted bounds when running a CD9 batch fix across a library.
155
+
156
+ ## Slots (2025 feature, Desktop Bridge)
157
+
158
+ Slots are open-ended content regions — the Figma-native answer to a `<slot>` / `children` prop. Reach for a Slot instead of a Variant matrix when the region's content is genuinely open-ended (a card's body, a dialog's footer actions, a menu's item list) rather than a fixed set of states — and note that Component Properties cannot be applied to layers _inside_ a slot.
159
+
160
+ | Tool | Use when… |
161
+ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
162
+ | `figma_create_slot` | Define a new SlotNode on a component/component set, with its linked SLOT property. (Bridge) |
163
+ | `figma_get_slots` | List the SlotNodes on a component, component set, or instance — read this before appending to or resetting one. (Bridge) |
164
+ | `figma_append_to_slot` | Clone or create content into an instance's slot — building a populated review/demo instance. (Bridge) |
165
+ | `figma_reset_slot` | Reset an instance's slot back to its default/empty state. (Bridge) |
166
+ | `figma_add_slot_property` | Manually bind an existing frame as a SLOT property — the alternative to `figma_create_slot` when the frame already exists. (Bridge) |
167
+
168
+ ## Validate — both modes
169
+
170
+ | Tool | Use when… |
171
+ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
172
+ | `figma_capture_screenshot` | **Plugin-side `exportAsync`** — captures live runtime state. **Prefer this immediately after a write**, because `figma_take_screenshot` (REST) can be cache-stale for several seconds. |
173
+ | `figma_take_screenshot` | REST-API screenshot. Standard validation step at the end of a sequence, when REST cache has caught up. Look for: cropped text, overlapping elements, placeholder text ("Heading", "Button" still visible), wrong color due to a bad variable alias. |
174
+ | `figma_audit_design_system` | Whole-file scorecard across six categories (Naming / Tokens / Components / A11y / Consistency / Coverage). Backs the Design System Dashboard MCP App. |
175
+ | `figma_audit_design_system_report` | JSON twin of the MCP-Apps Design System Dashboard — same six-category scorecard as scored, chunked JSON with per-finding fixability, cached ~5 min. Needs no `ENABLE_MCP_APPS`. |
176
+ | `figma_audit_component_accessibility` | Per-component accessibility scorecard with color-blind simulation. Use when the dashboard surfaces a component as A11y-bad and a deeper read is needed. |
177
+ | `figma_lint_design` | Rule-based linter — 14 WCAG + design-system-hygiene + layout rules, AA-tagged. Complementary to the two audit tools above; a finer-grained pass catches things the scorecards roll up. |
178
+ | `figma_analyze_component_set` | Variant state-machine + cross-variant diffs + CSS pseudo-class mapping. The right tool for CD7 (interactive-state coverage) audits — surfaces which states exist, which are missing, and where the variant diff is purely cosmetic vs. semantic. |
179
+ | `figma_get_design_changes` | Buffered change-events since the last call (live WebSocket, **not** a historical git-style diff). Useful inside an active Build/Migrate session for "what just moved", and as a Re-verify input within the same session. |
180
+ | `figma_check_design_parity` | Compare a Figma component's spec against a code implementation. Takes a `codeSpec` shaped as `{ visual, spacing, typography, tokens, componentAPI, accessibility, metadata }`; returns `{ score 0–100, discrepancies, actionItems }`. Most useful at the end of a Build or Sync run. |
181
+ | `figma_scan_code_accessibility` | Run axe-core against rendered HTML (Figma not required). Pairs with `figma_check_design_parity` via `mapToCodeSpec`; see `code-verify.md` for the round-trip recipe. |
182
+ | `figma_generate_component_doc` | Generate platform-agnostic Markdown documentation by merging Figma data with code-side info. Good handoff artifact after a build. |
183
+
184
+ ### Three audit tiers — they don't overlap
185
+
186
+ - `figma_audit_design_system` = whole-file scorecard. Run first.
187
+ - `figma_audit_component_accessibility` = single-component A11y deep-dive with color-blind simulation. Run on flagged components.
188
+ - `figma_lint_design` = rule-based linter for WCAG + DS-hygiene + layout. Run for fine-grained findings the scorecards skip.
189
+
190
+ In Audit mode, run all three. They surface different signals.
191
+
192
+ ## Annotations & Comments
193
+
194
+ Annotations are first-class **Dev-Mode handoff markers** — anchored to a node, surfaced in the Inspect panel, addressable via API. Comments are file-level discussion threads.
195
+
196
+ | Tool | Use when… |
197
+ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
198
+ | `figma_get_annotations` | Read designer-authored specs (markdown body + pinned properties). Sync-mode reads these as code-handoff hints. |
199
+ | `figma_set_annotations` | Write annotations after a Build — non-obvious behaviour (focus-ring delivery, animation easing, A11y notes) belongs here, not in the Component description. |
200
+ | `figma_get_annotation_categories` | List the available annotation categories before writing. |
201
+ | `figma_get_comments` | File comment threads. Mostly out of scope, but useful for parity-drift notification. |
202
+ | `figma_post_comment` | Optionally drop a comment on a frame when Sync-mode finds drift the user should see in-Figma. |
203
+ | `figma_delete_comment` | Remove a comment posted earlier in the same workflow. |
204
+
205
+ **Where annotations belong vs. descriptions.** Component description (`figma_set_description`) explains _what the component is and when to use it_. Annotation explains _the spot-specific implementation note an engineer needs while building_: "focus ring delivered as drop-shadow, not stroke", "this transition uses cubic-bezier(0.4,0,0.2,1)", "tap target extends 8px past the visible edge". One is the big picture; the other is the surgical detail.
206
+
207
+ ## History, changelog, blame, comments
208
+
209
+ | Tool | Use when… |
210
+ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
211
+ | `figma_get_file_versions` | List labeled version history, paginated (cap 200, default 50, autosaves excluded by default). (REST) |
212
+ | `figma_get_file_at_version` | Read a file/node snapshot as it existed at a past version. (REST) |
213
+ | `figma_diff_versions` | Page-level diff always; pass `component_ids` for a deeper node diff. Description/annotation deltas are only captured if the Bridge plugin was connected during the edit. (REST, Bridge improves coverage) |
214
+ | `figma_get_changes_since_version` | Convenience wrapper around `figma_diff_versions` — since a given version, to current. (REST) |
215
+ | `figma_generate_changelog` | Wraps `figma_diff_versions` into human-readable release notes (markdown + data). (REST) |
216
+ | `figma_blame_node` | Binary-search who/when introduced a change to a node or its property, walking up to 500 versions. (REST) |
217
+
218
+ Comment tools (`figma_get_comments`, `figma_post_comment`, `figma_delete_comment`) live in the Annotations & Comments section above.
219
+
220
+ **Coverage gap, inherited by all four version/diff tools above:** REST snapshots never carry description or annotation changes made while the Bridge plugin was disconnected during the edit, and never track variable _value_ changes, canvas instances, unbound raw layout/visual props, or style content — see each tool's `scope_coverage` / `notes[]` output.
221
+
222
+ ## Console & debugging — out of scope for this skill
223
+
224
+ `figma_get_console_logs`, `figma_watch_console`, `figma_clear_console`, `figma_reload_plugin`, `figma_reconnect` exist for debugging Figma plugins. Not relevant to workspace architecture. Mention them only if the user is actually plugin-debugging.
225
+
226
+ ## FigJam & Slides — out of scope for this skill
227
+
228
+ The MCP also exposes ~10 `figjam_*` tools for FigJam boards and ~15 `figma_*_slide` / `figma_list_slides` tools for Figma Slides decks. This skill targets **Figma Design files only** — workspaces, libraries, design systems. If the user asks about FigJam-board architecture or Slides decks, say so and decline rather than improvising.
229
+
230
+ ## Design-system extraction pipeline (`ds_*`, Local Mode only, code → Figma direction)
231
+
232
+ The reverse of this skill's usual Figma → spec → code flow: reverse-engineers an existing codebase into Figma-importable tokens plus a Storybook workshop. Local Mode only — reads and writes the local filesystem, not the live Figma document. Pipeline order:
233
+
234
+ | Tool | Use when… |
235
+ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
236
+ | `figma_ds_analyze` | Scan one or more app codebases: framework, styling approach, component inventory, and a porting-priority rank. Run first. |
237
+ | `figma_ds_extract_tokens` | Mine design tokens from the analyzed code into DTCG + CSS/Tailwind/SCSS/TS files. |
238
+ | `figma_ds_extract_component` | Deep single-component extraction — source, props, and a story scaffold. |
239
+ | `figma_ds_scaffold` | Generate the design-system package skeleton. |
240
+ | `figma_ds_setup_storybook` | Wire a freshly-initialized Storybook to the extracted tokens and fonts. |
241
+ | `figma_ds_status` | Read or update porting progress, persisted to disk. |
242
+ | `figma_ds_verify` | Fidelity-eval gate to run before handoff or before pushing tokens back into Figma. Run last. |
243
+
244
+ `ds_dashboard_refresh` refreshes the Design System Dashboard MCP App's data after a pipeline run changes the file. MCP App — needs `ENABLE_MCP_APPS=true`, same as the other MCP Apps in this map.
245
+
246
+ ## MCP Apps — interactive UI
247
+
248
+ When the client supports the MCP Apps protocol extension and `ENABLE_MCP_APPS=true` is set, two interactive panels are available:
249
+
250
+ - **Token Browser** — interactively browse, filter, and inspect Variables across modes. Useful as a "show me my tokens" view rather than dumping JSON into chat.
251
+ - **Design System Dashboard** — Lighthouse-style audit across six categories with severity-tagged findings. **Always run this first in Audit mode** before doing the architectural deep-audit; it covers breadth (especially A11y and Coverage) that this skill intentionally does not duplicate.
252
+
253
+ ## Decision shortcuts
254
+
255
+ - **About to create ≥3 variables in a loop?** Use `figma_batch_create_variables` instead.
256
+ - **Setting up a token system from scratch?** Use `figma_setup_design_tokens` — one atomic call beats four.
257
+ - **Built variant frames, want them as a component set?** Always `figma_arrange_component_set`, never hand-drawn containers.
258
+ - **Just created a component?** Don't return until `figma_set_description` AND `figma_set_annotations` have run, AND the containing Section/Frame is marked Ready-for-dev.
259
+ - **Need to do one rename / one resize / one fill?** Use the targeted node tool. Don't write a `figma_execute` for it.
260
+ - **Defining a Component Property?** Reach for `figma_add_component_property` first; only escalate to `figma_execute` if other mutations must happen atomically alongside.
261
+ - **First screenshot after a write?** `figma_capture_screenshot` (live), not `figma_take_screenshot` (REST cache).
262
+ - **About to call a destructive tool (`figma_delete_*`)?** Confirm with the user in chat first, even if they previously implied permission.
263
+ - **Generating a visual inventory / library catalog?** Don't load every component's metadata in one read. Phase 1 returns `{id, name, type}` only; Phase 4 builds cards **one Section per `figma_execute` call**, chunks of 25 with `setTimeout(0)` yields between chunks. Sections beyond ~150 components split across multiple calls. See `inventory-generation.md` § _Batching contract_.
264
+
265
+ ## Example payloads
266
+
267
+ Working snippets for the most common build operations. Treat them as starting points — adapt the names, modes, and scopes to the file at hand.
268
+
269
+ ### Bootstrap a 3-tier token system in one call
270
+
271
+ `figma_setup_design_tokens` is the fastest way to greenfield a real token architecture. The payload below sets up a `UI Tokens` collection with `Light` / `Dark` modes, a primitive primary palette, and semantic aliases that resolve through to those primitives. Variant Scopes are restricted to the slots each token actually belongs in.
272
+
273
+ ```json
274
+ {
275
+ "collectionName": "UI Tokens",
276
+ "modes": ["Light", "Dark"],
277
+ "variables": [
278
+ {
279
+ "name": "primitive/teal/600",
280
+ "type": "COLOR",
281
+ "scopes": ["FRAME_FILL", "SHAPE_FILL", "TEXT_FILL", "STROKE_COLOR"],
282
+ "valuesByMode": { "Light": "#007070", "Dark": "#0a8080" }
283
+ },
284
+ {
285
+ "name": "primitive/teal/700",
286
+ "type": "COLOR",
287
+ "scopes": ["FRAME_FILL", "SHAPE_FILL", "TEXT_FILL", "STROKE_COLOR"],
288
+ "valuesByMode": { "Light": "#005858", "Dark": "#0a6868" }
289
+ },
290
+ {
291
+ "name": "color/primary",
292
+ "type": "COLOR",
293
+ "scopes": ["FRAME_FILL", "SHAPE_FILL", "STROKE_COLOR"],
294
+ "valuesByMode": { "Light": { "alias": "primitive/teal/600" }, "Dark": { "alias": "primitive/teal/600" } }
295
+ },
296
+ {
297
+ "name": "color/primary-hover",
298
+ "type": "COLOR",
299
+ "scopes": ["FRAME_FILL", "SHAPE_FILL", "STROKE_COLOR"],
300
+ "valuesByMode": { "Light": { "alias": "primitive/teal/700" }, "Dark": { "alias": "primitive/teal/700" } }
301
+ },
302
+ {
303
+ "name": "spacing/4",
304
+ "type": "FLOAT",
305
+ "scopes": ["GAP", "WIDTH_HEIGHT"],
306
+ "valuesByMode": { "Light": 16, "Dark": 16 }
307
+ }
308
+ ]
309
+ }
310
+ ```
311
+
312
+ Pattern notes:
313
+
314
+ - **Primitives** (`primitive/*`) carry the actual hex / number; their scopes are the most permissive valid set.
315
+ - **Semantic** tokens (`color/primary`, `color/primary-hover`) alias primitives via `{ "alias": "primitive/..." }`. Their scopes are tighter — semantic colors should not appear in spacing pickers.
316
+ - **Modes** carry theming. Each Variable has a value (or alias) per mode.
317
+ - **Spacing tokens** are `FLOAT`, not `COLOR`. Don't mix them in one collection unless the system genuinely treats them uniformly.
318
+
319
+ ### Set Variable Scopes after creation (`figma_execute`)
320
+
321
+ `figma_setup_design_tokens` accepts `scopes` directly, but `figma_create_variable` and the batch flavors do not. Restrict scopes after creation via Plugin API:
322
+
323
+ ```js
324
+ // figma_execute payload
325
+ const variable = await figma.variables.getVariableByIdAsync('VariableID:1234:5');
326
+ variable.scopes = ['FRAME_FILL', 'SHAPE_FILL', 'STROKE_COLOR'];
327
+ return { id: variable.id, scopes: variable.scopes };
328
+ ```
329
+
330
+ `ALL_FILLS` is mutually exclusive with the specific fill scopes — pick one set or the other, not both.
331
+
332
+ ### Create a single-variant Component with a primary fill bound to a Variable
333
+
334
+ The `build → arrange → describe` pattern in code. Three calls; `figma_execute` for the geometry, `figma_arrange_component_set` for the container, `figma_set_description` for discoverability.
335
+
336
+ ```js
337
+ // figma_execute — build the variant frame
338
+ await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
339
+
340
+ const frame = figma.createFrame();
341
+ frame.name = 'variant=primary, size=md';
342
+ frame.layoutMode = 'HORIZONTAL';
343
+ frame.primaryAxisAlignItems = 'CENTER';
344
+ frame.counterAxisAlignItems = 'CENTER';
345
+ frame.paddingLeft = frame.paddingRight = 16;
346
+ frame.paddingTop = frame.paddingBottom = 8;
347
+ frame.itemSpacing = 8;
348
+ frame.cornerRadius = 8;
349
+ frame.layoutSizingHorizontal = 'HUG';
350
+ frame.layoutSizingVertical = 'HUG';
351
+
352
+ // Bind fill to the semantic Variable
353
+ const primary = await figma.variables.getVariableByIdAsync('VariableID:1234:5');
354
+ const fill = { type: 'SOLID', color: { r: 0, g: 0.44, b: 0.44 } };
355
+ frame.fills = [figma.variables.setBoundVariableForPaint(fill, 'color', primary)];
356
+
357
+ // Label
358
+ const label = figma.createText();
359
+ label.fontName = { family: 'Inter', style: 'Medium' };
360
+ label.characters = 'Button';
361
+ label.fontSize = 14;
362
+ label.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
363
+ frame.appendChild(label);
364
+
365
+ // Promote to a component
366
+ const component = figma.createComponentFromNode(frame);
367
+ return { id: component.id, name: component.name };
368
+ ```
369
+
370
+ Then call `figma_arrange_component_set` with the array of component IDs (one per variant) to wrap them in the proper Component Set frame, and `figma_set_description` to attach markdown documentation.
371
+
372
+ ### Add a new Mode to an existing collection
373
+
374
+ ```js
375
+ // figma_execute — add a "Compact" density mode and seed its values
376
+ const collection = await figma.variables.getVariableCollectionByIdAsync('VariableCollectionId:1234:0');
377
+ const newModeId = collection.addMode('Compact');
378
+
379
+ // Seed the spacing/4 Variable in the new mode (smaller value for compact density)
380
+ const spacing4 = await figma.variables.getVariableByIdAsync('VariableID:1234:7');
381
+ spacing4.setValueForMode(newModeId, 12);
382
+
383
+ return { newModeId, modes: collection.modes.map((m) => m.name) };
384
+ ```
385
+
386
+ Modes scale linearly per Variable — adding a mode is cheap, but you now have **N × M** values to maintain. Audit for "hidden" Variables that fall back to default and check the user actually wants that.
387
+
388
+ ### Validation pattern after any meaningful write
389
+
390
+ ```js
391
+ // Right after a build, screenshot the Components page bounding box
392
+ const node = await figma.getNodeByIdAsync('123:456'); // the parent section / page
393
+ const settings = { format: 'PNG', constraint: { type: 'SCALE', value: 1 } };
394
+ const bytes = await node.exportAsync(settings);
395
+ return { bytes: bytes.length }; // confirm it rendered before pulling the image via figma_take_screenshot
396
+ ```
397
+
398
+ Use `figma_take_screenshot` directly when the goal is to look at the result; use the snippet above when the goal is purely to confirm the node is renderable (catches "0×0 frame" bugs cheaply).