use_figma — Figma Plugin API Skill

Use the use_figma tool 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.

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 loading is required before ANY operation on nodes that contain unloaded fonts — not just text-setting operations. This includes appendChild, insertChild, setBoundVariable, setExplicitVariableModeForCollection, setValueForMode, and even findAll callbacks. If the document has existing text nodes, preload all their fonts at the start of the script. Use await figma.listAvailableFontsAsync() to discover available fonts and styles, then await figma.loadFontAsync({family, style}) to load each one. See Gotchas for the full preload pattern.
9. 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)
10. setBoundVariableForPaint returns a NEW paint — must capture and reassign