Name: figma-use
Author: figma

**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 the use figma tool to execute JavaScript in Figma files via the Plugin API. All detailed reference docs live in references/ . When available, call create session with fileKey and description before file reads or edits (create the file first if needed), then pass the returned sessionId unchanged to every call that accepts it, including follow ups and work across files. Always include figma use in the comma separated skillNames parameter when calling use figma . If this skill was loaded via an MCP resource, you MUST prefix the name with resource: (e.g. resource:figma use ). This is a logging parameter used to track skill usage — it does not affect execution. If Figma MCP tools appear as deferred tools, batch load all their schemas in a single ToolSearch call using the select: syntax — e.g. ToolSearch query="select:use figma,get screenshot,get metadata,create new file" . One round trip beats six. MANDATORY for visible design changes: Before the first mutating use figma call, load [figma generate design](../figma generate design/SKILL.md) alongside this skill and include both names in every mutating call’s skillNames . This applies from a single visible property or element to a full page, screen, or composed multi section view—even when the user calls that view a component. figma use provides the Plugin API rules; figma generate design provides design system discovery through search design system , asset importing, and incremental assembly. Reusable library exception: If the primary deliverable is a reusable component, component set, variant system, variable/token collection, style foundation, or other library asset intended for reuse or publication, load [figma generate library](../figma generate library/SKILL.md) instead. It provides the component creation workflow—variable foundations, variant sets, and design token bindings—that figma use alone does not cover. For tasks that include both library assets and a composed design that uses them, load both companion skills. Read only use figma calls need neither. 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. Return node IDs and keep workflow state outside the Figma file. Set human readable component purpose and usage in node.description only on a COMPONENT or COMPONENT SET — never on a frame or instance. 3b. Narrow before accessing type specific properties. Check node.type , use a capability guard such as "characters" in node , or prefilter with findAllWithCriteria . characters requires a text capable node; optional chaining does not protect unsupported property access. 4. console.log() is NOT returned — use return for output 5. Size construction calls for safe retry and validate from evidence. Do not split a working operation solely to create validation checkpoints. Batch related work when the resulting script remains safe to retry; a complete section or page may be built in one call. Split when crossing page context, when partial execution would be difficult to recover, or after an actual failure requires a targeted retry. Return affected IDs and relevant counts, names, or bounds from each write—this counts as structural validation. Run a separate structural check only when required evidence is missing or after a relevant mutation. Normally take one screenshot after composition and one after a visual fix. The most recent passing screenshot is the final check; do not repeat it when nothing relevant changed. Stop once requirements pass. 6. Colors are 0–1 range (not 0–255): {r: 1, g: 0, b: 0} = red. Paint color objects use {r, g, b} only — no a field ; opacity goes at the paint level ( { type: 'SOLID', color: {...}, opacity: 0.5 } ). 7. Fills/strokes are read only arrays — clone, modify, reassign 8. Every text edit follows the canonical recipe: load font → await → mutate → return affected node IDs. Skipping the load throws Cannot write to node with unloaded font "<family <style " . The rule covers more than characters — it applies to any operation on nodes with unloaded fonts ( appendChild , insertChild , setBoundVariable , setExplicitVariableModeForCollection , setValueForMode , findAll callbacks touching text). When mutating existing text, load the node's current fonts via getStyledTextSegments(['fontName']) , not a hardcoded default. Inter is preloaded in most environments so other families surface this bug more often — the recipe is the same for every font. Use await figma.listAvailableFontsAsync() first if the style string is unverified — never guess ( "SemiBold" vs "Semi Bold" is a common footgun). For FONT FAMILY scoped variables, load every value across every relevant mode before setBoundVariable("fontFamily", …) , setValueForMode , or setExplicitVariableModeForCollection . lineHeight / letterSpacing take {unit, value} , not bare numbers. See [Canonical text edit recipe](references/gotchas.md canonical text edit recipe font load await mutate return ids). 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 throws "Setting figma.currentPage is not supported" . Page context resets to the first page at the start of every use figma call, so re switch each call; switch at most once per call and fan multi page work out in parallel — see [Page Rules]( 2 page rules critical) and [gotchas.md](references/gotchas.md set current page once per use figma call split multi page work into parallel calls). 10. setBoundVariableForPaint returns a NEW paint — must capture and reassign 11. createVariable accepts collection object or ID string (object preferred) 12. layoutSizingHorizontal/Vertical is value restricted by structural context — FIXED always works, HUG and FILL do not. 'HUG' is valid only on an auto layout frame itself OR on a TEXT child of one. 'FILL' is valid only on a child of an auto layout frame that is also not absolute positioned, not inside an immutable frame, and not a canvas grid child. Practical consequence: append to an auto layout parent FIRST, then set HUG / FILL — a newly created or unparented node can't satisfy the rule yet. The property itself exists on every SceneNode ; the error is value rejection, not "no such property". See [Gotchas](references/gotchas.md layoutsizinghorizontallayoutsizingvertical value rules fixed hug fill). 12a. Use auto layout for containers that hold related children. When children have a structural relationship — stacked, side by side, aligned, gapped, hugged — wrap them in figma.createAutoLayout() , not figma.createFrame() with absolute x / y . Absolute coordinates govern where a container sits on the canvas; auto layout governs how its children relate inside it. Skipping the container leaves no protection against text reflow, content changes, or overlap. 12b. layoutSizing and AxisSizingMode are different enums — don't cross them. layoutSizingHorizontal / layoutSizingVertical (set on a child ) take 'FIXED' 'HUG' 'FILL' ; primaryAxisSizingMode / counterAxisSizingMode (set on the frame itself) take 'FIXED' 'AUTO' . So layoutSizingVertical = 'AUTO' is invalid (use 'HUG' ), and counterAxisSizingMode = 'FILL' throws Expected 'FIXED' 'AUTO', received 'FILL' (use 'FIXED' / 'AUTO' ). Two more errors from the same setter — Error: in set layoutSizingHorizontal: node must be an auto layout frame or a child of an auto layout frame and Error: in set layoutSizingHorizontal: FILL can only be set on children of auto layout frames — mean the node isn't in an auto layout context yet; recommendation: make the parent auto layout ( figma.createAutoLayout() ) and appendChild the node before setting (see Rule 12). See [Gotchas](references/gotchas.md layoutsizing vs axissizingmode two different sizing enums). 12c. resize() resets sizing modes to FIXED , so call it BEFORE setting layoutSizing . A wrapping TEXT block needs textAutoResize = 'HEIGHT' plus an explicit FIXED width ( resize() ), NOT FILL alone — the default WIDTH AND HEIGHT mode ignores FILL and collapses the node to a near zero width thread. Verify node.width 0 afterward. 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, obey safeToRetryWithoutCanvasRead . If true , fix the error and retry. If false , read the canvas, determine what changed, then make changes. See [Error Recovery]( 7 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. No state persists across use figma calls, so pass IDs from previous calls as string literals , not variables. See [common patterns.md](references/common patterns.md) for worked multi step examples. 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. 18. Never read componentPropertyDefinitions from a variant component. Narrow the owner first: use the node itself when it is a COMPONENT SET , use a COMPONENT only when its parent is not a COMPONENT SET , and otherwise promote a variant COMPONENT to its parent set. Optional chaining does not make the getter safe. See [Component property owner narrowing](references/component patterns.md component property owner narrowing). 19. Never read componentPropertyDefinitions , componentProperties , or valuesByMode across a collection