**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 requ

use figma — Figma Plugin API Skill Use use figma MCP to execute JavaScript in Figma files via the Plugin API. All detailed reference docs live in references/ . Always pass skillNames: "figma use" when calling use figma . This is a logging parameter used to track skill usage — it does not affect execution. 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. Before 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. IMPORTANT: 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. 1. Critical Rules 1. 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. 2. Write plain JavaScript with top level await and return . Code is automatically wrapped in an async context. Do NOT wrap in (async () = { ... })() . 3. figma.notify() throws "not implemented" — never use it 3a. 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. 4. console.log() is NOT returned — use return for output 5. 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. 6. Colors are 0–1 range (not 0–255): {r: 1, g: 0, b: 0} = red 7. Fills/strokes are read only arrays — clone, modify, reassign 8. Font MUST be loaded before any text operation: await figma.loadFontAsync({family, style}) 9. Pages load incrementally — use await figma.setCurrentPageAsync(page) to switch pages and load their content (see Page Rules below) 10. setBoundVariableForPaint returns a NEW paint — must capture and reassign 11. createVariable accepts collection object or ID string (object preferred) 12. layoutSizingHorizontal/Vertical = 'FILL' MUST be set AFTER parent.appendChild(child) — setting before append throws. Same applies to 'HUG' on non auto layout nodes. 13. 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). 14. 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). 15. 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. 16. 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. 17. 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. For detailed WRONG/CORRECT examples of each rule, see [Gotchas & Common Mistakes](references/gotchas.md). 2. Page Rules (Critical) Page context resets between use figma calls — figma.currentPage starts on the first page each time. Switching pages Use await figma.setCurrentPageAsync(page) to switch pages and load their content. The sync setter figma.currentPage = page throws an error in use figma runtimes. Across script runs 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. You 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. 3. return Is Your Output Channel The agent sees ONLY the value you return . Everything else is invisible. 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. Progress reporting : return { createdNodeIds: [...], count: 5, errors: [] } Error info : Thrown errors are automatically captured and returned — just let them propagate or throw explicitly. console.log() output is never returned to the agent Always return actionable data (IDs, counts, status) so subsequent calls can reference created objects 4. Editor Mode 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. Available in design mode: Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Page, Section, TextPath. Blocked in design mode: Sticky, Connector, ShapeWithText, CodeBlock, Slide, SlideRow, Webpage. 5. Incremental Workflow (How to Avoid Bugs) The 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. The pattern 1. 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. 2. 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. 3. 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. 4. Validate after each step. Use get metadata to verify structure (counts, names, hierarchy, positions). Use get screenshot after major milestones to catch visual issues. 5. Fix before moving on. If validation reveals a problem, fix it before proceeding to the next step. Don't build on a broken foundation. Suggested step order for complex tasks What to validate at each step After... Check with get metadata Check with get screenshot Creating variables Collection count, variable count, mode names — Creating components Child count, variant names, property definitions Variants visible, not collapsed, grid readable Binding variables Node properties reflect bindings Colors/tokens resolved correctly Composing layouts Instance nodes have mainComponent, hierarchy correct No cropped/clipped text, no overlapping elements, correct spacing 6. Error Recovery & Self Correction 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. When use figma returns an error 1. STOP. Do not immediately fix the code and retry. 2. Read the error message carefully. Understand exactly what went wrong — wrong API usage, missing font, invalid property value, etc. 3. If the error is unclear , call get metadata or get screenshot to understand the current file state. 4. Fix the script based on the error message. 5. Retry the corrected script. Common self correction patterns Error message Likely cause How to fix "not implemented" Used figma.notify() Remove it — use return for output "node must be an auto layout frame..." Set FILL / HUG before appending to auto layout parent Move appendChild before layoutSizingX = 'FILL' "Setting figma.currentPage is not supported" Used sync page setter Use await figma.setCurrentPageAsync(page) Property value out of range Color channel 1 (used 0–255 instead of 0–1) Divide by 255 "Cannot read properties of null" Node doesn't exist (wrong ID, wrong page) Check page context, verify ID Script hangs / no response Infinite loop or unresolved promise Check for while(true) or missing await ; ensure code terminates "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 When the script succeeds but the result looks wrong 1. Call get metadata to check structural correctness (hierarchy, counts, positions). 2. 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. 3. Identify the discrepancy — is it structural (wrong hierarchy, missing nodes) or visual (wrong colors, broken layout, clipped content)? 4. Write a targeted fix script that modifies only the broken parts — don't recreate everything. For the full validation workflow, see [Validation & Error Recovery](references/validation and recovery.md). 7. Pre Flight Checklist Before submitting ANY use figma call, verify: [ ] Code uses return to send data back (NOT figma.closePlugin() ) [ ] Code is NOT wrapped in an async IIFE (auto wrapped for you) [ ] return value includes structured data with actionable info (IDs, counts) [ ] NO usage of figma.notify() anywhere [ ] NO usage of console.log() as output (use return instead) [ ] All colors use 0–1 range (not 0–255) [ ] Fills/strokes are reassigned as new arrays (not mutated in place) [ ] Page switches use await figma.setCurrentPageAsync(page) (sync setter throws) [ ] layoutSizingVertical/Horizontal = 'FILL' is set AFTER parent.appendChild(child) [ ] loadFontAsync() called BEFORE any text property changes [ ] lineHeight / letterSpacing use {unit,

figma-use