figma-use

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. 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 to understand what is possible. When you are asked to write plugin API code, use this context to grep 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 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.

• 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. • Write plain JavaScript with top-level await and return. Code is automatically wrapped in an async context. Do NOT wrap in (async () => { ... })(). • 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. • console.log() is NOT returned — use return for output • 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. • Colors are 0–1 range (not 0–255): {r: 1, g: 0, b: 0} = red • Fills/strokes are read-only arrays — clone, modify, reassign • Font MUST be loaded before any text operation: await figma.loadFontAsync({family, style}) • Pages load incrementally — use await figma.setCurrentPageAsync(page) to switch pages and load their content (see Page Rules below) • setBoundVariableForPaint returns a NEW paint — must capture and reassign • createVariable accepts collection object or ID string (object preferred) • layoutSizingHorizontal/Vertical = 'FILL' MUST be set AFTER parent.appendChild(child) — setting before append throws. Same applies to 'HUG' on non-auto-layout nodes. • 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. • 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. • 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. • 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 for the full list. • 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.

Page context resets between use_figma calls — figma.currentPage starts on the first page each time.

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. `js // Switch to a specific page (loads its content) const targetPage = figma.root.children.find((p) => p.name === "My Page"); await figma.setCurrentPageAsync(targetPage); // targetPage.children is now populated // Iterate over all pages for (const page of figma.root.children) { await figma.setCurrentPageAsync(page); // page.children is now loaded — read or modify them here } `