Figma Use

1---2name: figma-use3description: "**MANDATORY prerequisite** — you MUST invoke this skill BEFORE every `use_figma` tool call. NEVER call `use_figma` directly without loading this skill first. Skipping it causes common, hard-to-debug failures. Trigger whenever the user wants to perform a write action or a unique read action that requires JavaScript execution in the Figma file context — e.g. create/edit/delete nodes, set up variables or tokens, build components and variants, modify auto-layout or fills, bind variables to properties, or inspect file structure programmatically."4disable-model-invocation: false5---6 7# use_figma — Figma Plugin API Skill8 9Use the `use_figma` tool to execute JavaScript in Figma files via the Plugin API. All detailed reference docs live in `references/`.10 11**Always pass `skillNames: "figma-use"` when calling `use_figma`.** This is a logging parameter used to track skill usage — it does not affect execution.12 13**If the task involves building or updating a full page, screen, or multi-section layout in Figma from code**, also load [figma-generate-design](../figma-generate-design/SKILL.md). It provides the workflow for discovering design system components via `search_design_system`, importing them, and assembling screens incrementally. Both skills work together: this one for the API rules, that one for the screen-building workflow.14 15Before anything, load [plugin-api-standalone.index.md](references/plugin-api-standalone.index.md) to understand what is possible. When you are asked to write plugin API code, use this context to grep [plugin-api-standalone.d.ts](references/plugin-api-standalone.d.ts) for relevant types, methods, and properties. This is the definitive source of truth for the API surface. It is a large typings file, so do not load it all at once, grep for relevant sections as needed.16 17IMPORTANT: Whenever you work with design systems, start with [working-with-design-systems/wwds.md](references/working-with-design-systems/wwds.md) to understand the key concepts, processes, and guidelines for working with design systems in Figma. Then load the more specific references for components, variables, text styles, and effect styles as needed.18 19## 1. Critical Rules20 211.  **Use `return` to send data back.** The return value is JSON-serialized automatically (objects, arrays, strings, numbers). Do NOT call `figma.closePlugin()` or wrap code in an async IIFE — this is handled for you.222.  **Write plain JavaScript with top-level `await` and `return`.** Code is automatically wrapped in an async context. Do NOT wrap in `(async () => { ... })()`.233.  `figma.notify()` **throws "not implemented"** — never use it243a. `getPluginData()` / `setPluginData()` are **not supported** in `use_figma` — do not use them. Use `getSharedPluginData()` / `setSharedPluginData()` instead (these ARE supported), or track node IDs by returning them and passing them to subsequent calls.254.  `console.log()` is NOT returned — use `return` for output265.  **Work incrementally in small steps.** Break large operations into multiple `use_figma` calls. Validate after each step. This is the single most important practice for avoiding bugs.276.  Colors are **0–1 range** (not 0–255): `{r: 1, g: 0, b: 0}` = red287.  Fills/strokes are **read-only arrays** — clone, modify, reassign298.  Font **MUST** be loaded before any text operation: `await figma.loadFontAsync({family, style})`. Use `await figma.listAvailableFontsAsync()` to discover all available fonts and their exact style strings — if a `loadFontAsync` call fails, call `listAvailableFontsAsync()` to find the correct style name or pick a fallback.309.  **Pages load incrementally** — use `await figma.setCurrentPageAsync(page)` to switch pages and load their content. The sync setter `figma.currentPage = page` does **NOT** work and will throw (see Page Rules below)3110. `setBoundVariableForPaint` returns a **NEW** paint — must capture and reassign3211. `createVariable` accepts collection **object or ID string** (object preferred)3312. **`layoutSizingHorizontal/Vertical = 'FILL'` MUST be set AFTER `parent.appendChild(child)`** — setting before append throws. Same applies to `'HUG'` on non-auto-layout nodes.3413. **Position new top-level nodes away from (0,0).** Nodes appended directly to the page default to (0,0). Scan `figma.currentPage.children` to find a clear position (e.g., to the right of the rightmost node). This only applies to page-level nodes — nodes nested inside other frames or auto-layout containers are positioned by their parent. See [Gotchas](references/gotchas.md).3514. **On `use_figma` error, STOP. Do NOT immediately retry.** Failed scripts are **atomic** — if a script errors, it is not executed at all and no changes are made to the file. Read the error message carefully, fix the script, then retry. See [Error Recovery](#6-error-recovery--self-correction).3615. **MUST `return` ALL created/mutated node IDs.** Whenever a script creates new nodes or mutates existing ones on the canvas, collect every affected node ID and return them in a structured object (e.g. `return { createdNodeIds: [...], mutatedNodeIds: [...] }`). This is essential for subsequent calls to reference, validate, or clean up those nodes.3716. **Always set `variable.scopes` explicitly when creating variables.** The default `ALL_SCOPES` pollutes every property picker — almost never what you want. Use specific scopes like `["FRAME_FILL", "SHAPE_FILL"]` for backgrounds, `["TEXT_FILL"]` for text colors, `["GAP"]` for spacing, etc. See [variable-patterns.md](references/variable-patterns.md) for the full list.3817. **`await` every Promise.** Never leave a Promise unawaited — unawaited async calls (e.g. `figma.loadFontAsync(...)` without `await`, or `figma.setCurrentPageAsync(page)` without `await`) will fire-and-forget, causing silent failures or race conditions. The script may return before the async operation completes, leading to missing data or half-applied changes.39 40> For detailed WRONG/CORRECT examples of each rule, see [Gotchas & Common Mistakes](references/gotchas.md).41 42## 2. Page Rules (Critical)43 44**Page context resets between `use_figma` calls** — `figma.currentPage` starts on the first page each time.45 46### Switching pages47 48Use `await figma.setCurrentPageAsync(page)` to switch pages and load their content. The sync setter `figma.currentPage = page` does **NOT work** — it throws `"Setting figma.currentPage is not supported"` in `use_figma`. Always use the async method.49 50```js51// Switch to a specific page (loads its content)52const targetPage = figma.root.children.find((p) => p.name === "My Page");53await figma.setCurrentPageAsync(targetPage);54// targetPage.children is now populated55 56// Iterate over all pages57for (const page of figma.root.children) {58  await figma.setCurrentPageAsync(page);59  // page.children is now loaded — read or modify them here60}61```62 63### Across script runs64 65`figma.currentPage` resets to the **first page** at the start of each `use_figma` call. If your workflow spans multiple calls and targets a non-default page, call `await figma.setCurrentPageAsync(page)` at the start of each invocation.66 67You can call `use_figma` multiple times to incrementally build on the file state, or to retrieve information before writing another script. For example, write a script to get metadata about existing nodes, `return` that data, then use it in a subsequent script to modify those nodes.68 69## 3. `return` Is Your Output Channel70 71The agent sees **ONLY** the value you `return`. Everything else is invisible.72 73- **Returning IDs (CRITICAL)**: Every script that creates or mutates canvas nodes **MUST** return all affected node IDs — e.g. `return { createdNodeIds: [...], mutatedNodeIds: [...] }`. This is a hard requirement, not optional.74- **Progress reporting**: `return { createdNodeIds: [...], count: 5, errors: [] }`75- **Error info**: Thrown errors are automatically captured and returned — just let them propagate or `throw` explicitly.76- `console.log()` output is **never** returned to the agent77- Always return actionable data (IDs, counts, status) so subsequent calls can reference created objects78 79## 4. Editor Mode80 81`use_figma` works in **design mode** (editorType `"figma"`, the default). FigJam (`"figjam"`) has a different set of available node types — most design nodes are blocked there.82 83Available in design mode: Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Page, Section, TextPath.84 85**Blocked** in design mode: Sticky, Connector, ShapeWithText, CodeBlock, Slide, SlideRow, Webpage.86 87## 5. Incremental Workflow (How to Avoid Bugs)88 89The most common cause of bugs is trying to do too much in a single `use_figma` call. **Work in small steps and validate after each one.**90 91### The pattern92 931. **Inspect first.** Before creating anything, run a read-only `use_figma` to discover what already exists in the file — pages, components, variables, naming conventions. Match what's there.942. **Do one thing per call.** Create variables in one call, create components in the next, compose layouts in another. Don't try to build an entire screen in one script.953. **Return IDs from every call.** Always `return` created node IDs, variable IDs, collection IDs as objects (e.g. `return { createdNodeIds: [...] }`). You'll need these as inputs to subsequent calls.964. **Validate after each step.** Use `get_metadata` to verify structure (counts, names, hierarchy, positions). Use `get_screenshot` after major milestones to catch visual issues.975. **Fix before moving on.** If validation reveals a problem, fix it before proceeding to the next step. Don't build on a broken foundation.98 99### Suggested step order for complex tasks100 101```102Step 1: Inspect file — discover existing pages, components, variables, conventions103Step 2: Create tokens/variables (if needed)104       → validate with get_metadata105Step 3: Create individual components106       → validate with get_metadata + get_screenshot107Step 4: Compose layouts from component instances108       → validate with get_screenshot109Step 5: Final verification110```111 112### What to validate at each step113 114| After... | Check with `get_metadata` | Check with `get_screenshot` |115|---|---|---|116| Creating variables | Collection count, variable count, mode names | — |117| Creating components | Child count, variant names, property definitions | Variants visible, not collapsed, grid readable |118| Binding variables | Node properties reflect bindings | Colors/tokens resolved correctly |119| Composing layouts | Instance nodes have mainComponent, hierarchy correct | No cropped/clipped text, no overlapping elements, correct spacing |120 121## 6. Error Recovery & Self-Correction122 123**`use_figma` is atomic — failed scripts do not execute.** If a script errors, no changes are made to the file. The file remains in the same state as before the call. This means there are no partial nodes, no orphaned elements from the failed script, and retrying after a fix is safe.124 125### When `use_figma` returns an error126 1271. **STOP.** Do not immediately fix the code and retry.1282. **Read the error message carefully.** Understand exactly what went wrong — wrong API usage, missing font, invalid property value, etc.1293. **If the error is unclear**, call `get_metadata` or `get_screenshot` to understand the current file state.1304. **Fix the script** based on the error message.1315. **Retry** the corrected script.132 133### Common self-correction patterns134 135| Error message | Likely cause | How to fix |136|---|---|---|137| `"not implemented"` | Used `figma.notify()` | Remove it — use `return` for output |138| `"node must be an auto-layout frame..."` | Set `FILL`/`HUG` before appending to auto-layout parent | Move `appendChild` before `layoutSizingX = 'FILL'` |139| `"Setting figma.currentPage is not supported"` | Used sync page setter (`figma.currentPage = page`) which does NOT work | Use `await figma.setCurrentPageAsync(page)` — the only way to switch pages |140| Property value out of range | Color channel > 1 (used 0–255 instead of 0–1) | Divide by 255 |141| `"Cannot read properties of null"` | Node doesn't exist (wrong ID, wrong page) | Check page context, verify ID |142| Script hangs / no response | Infinite loop or unresolved promise | Check for `while(true)` or missing `await`; ensure code terminates |143| `"The node with id X does not exist"` | Parent instance was implicitly detached by a child `detachInstance()`, changing IDs | Re-discover nodes by traversal from a stable (non-instance) parent frame |144 145### When the script succeeds but the result looks wrong146 1471. Call `get_metadata` to check structural correctness (hierarchy, counts, positions).1482. Call `get_screenshot` to check visual correctness. Look closely for cropped/clipped text (line heights cutting off content) and overlapping elements — these are common and easy to miss.1493. Identify the discrepancy — is it structural (wrong hierarchy, missing nodes) or visual (wrong colors, broken layout, clipped content)?1504. Write a targeted fix script that modifies only the broken parts — don't recreate everything.151 152> For the full validation workflow, see [Validation & Error Recovery](references/validation-and-recovery.md).153 154## 7. Pre-Flight Checklist155 156Before submitting ANY `use_figma` call, verify:157 158- [ ] Code uses `return` to send data back (NOT `figma.closePlugin()`)159- [ ] Code is NOT wrapped in an async IIFE (auto-wrapped for you)160- [ ] `return` value includes structured data with actionable info (IDs, counts)161- [ ] NO usage of `figma.notify()` anywhere162- [ ] NO usage of `console.log()` as output (use `return` instead)163- [ ] All colors use 0–1 range (not 0–255)164- [ ] Paint `color` objects use `{r, g, b}` only — no `a` field (opacity goes at the paint level: `{ type: 'SOLID', color: {...}, opacity: 0.5 }`)165- [ ] Fills/strokes are reassigned as new arrays (not mutated in place)166- [ ] Page switches use `await figma.setCurrentPageAsync(page)` (sync setter `figma.currentPage = page` does NOT work)167- [ ] `layoutSizingVertical/Horizontal = 'FILL'` is set AFTER `parent.appendChild(child)`168- [ ] `loadFontAsync()` called BEFORE any text property changes (use `listAvailableFontsAsync()` to verify font availability if unsure)169- [ ] `lineHeight`/`letterSpacing` use `{unit, value}` format (not bare numbers)170- [ ] `resize()` is called BEFORE setting sizing modes (resize resets them to FIXED)171- [ ] For multi-step workflows: IDs from previous calls are passed as string literals (not variables)172- [ ] New top-level nodes are positioned away from (0,0) to avoid overlapping existing content173- [ ] ALL created/mutated node IDs are collected and included in the `return` value174- [ ] Every async call (`loadFontAsync`, `setCurrentPageAsync`, `importComponentByKeyAsync`, etc.) is `await`ed — no fire-and-forget Promises175 176## 8. Discover Conventions Before Creating177 178**Always inspect the Figma file before creating anything.** Different files use different naming conventions, variable structures, and component patterns. Your code should match what's already there, not impose new conventions.179 180When in doubt about any convention (naming, scoping, structure), check the Figma file first, then the user's codebase. Only fall back to common patterns when neither exists.181 182### Quick inspection scripts183 184**List all pages and top-level nodes:**185```js186const pages = figma.root.children.map(p => `${p.name} id=${p.id} children=${p.children.length}`);187return pages.join('\n');188```189 190**List existing components across all pages:**191```js192const results = [];193for (const page of figma.root.children) {194  await figma.setCurrentPageAsync(page);195  page.findAll(n => {196    if (n.type === 'COMPONENT' || n.type === 'COMPONENT_SET')197      results.push(`[${page.name}] ${n.name} (${n.type}) id=${n.id}`);198    return false;199  });200}201return results.join('\n');202```203 204**List existing variable collections and their conventions:**205```js206const collections = await figma.variables.getLocalVariableCollectionsAsync();207const results = collections.map(c => ({208  name: c.name, id: c.id,209  varCount: c.variableIds.length,210  modes: c.modes.map(m => m.name)211}));212return results;213```214 215## 9. Reference Docs216 217Load these as needed based on what your task involves:218 219| Doc | When to load | What it covers |220|-----|-------------|----------------|221| [gotchas.md](references/gotchas.md) | Before any `use_figma` | Every known pitfall with WRONG/CORRECT code examples |222| [common-patterns.md](references/common-patterns.md) | Need working code examples | Script scaffolds: shapes, text, auto-layout, variables, components, multi-step workflows |223| [plugin-api-patterns.md](references/plugin-api-patterns.md) | Creating/editing nodes | Fills, strokes, Auto Layout, effects, grouping, cloning, styles |224| [api-reference.md](references/api-reference.md) | Need exact API surface | Node creation, variables API, core properties, what works and what doesn't |225| [validation-and-recovery.md](references/validation-and-recovery.md) | Multi-step writes or error recovery | `get_metadata` vs `get_screenshot` workflow, mandatory error recovery steps |226| [component-patterns.md](references/component-patterns.md) | Creating components/variants | combineAsVariants, component properties, INSTANCE_SWAP, variant layout, discovering existing components, metadata traversal |227| [variable-patterns.md](references/variable-patterns.md) | Creating/binding variables | Collections, modes, scopes, aliasing, binding patterns, discovering existing variables |228| [text-style-patterns.md](references/text-style-patterns.md) | Creating/applying text styles | Type ramps, font discovery via `listAvailableFontsAsync`, listing styles, applying styles to nodes |229| [effect-style-patterns.md](references/effect-style-patterns.md) | Creating/applying effect styles | Drop shadows, listing styles, applying styles to nodes |230| [plugin-api-standalone.index.md](references/plugin-api-standalone.index.md) | Need to understand the full API surface | Index of all types, methods, and properties in the Plugin API |231| [plugin-api-standalone.d.ts](references/plugin-api-standalone.d.ts) | Need exact type signatures | Full typings file — grep for specific symbols, don't load all at once |232 233## 10. Snippet examples234 235You will see snippets throughout documentation here. These snippets contain useful plugin API code that can be repurposed. Use them as is, or as starter code as you go. If there are key concepts that are best documented as generic snippets, call them out and write to disk so you can reuse in the future.