Figma Use

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 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.

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.

If the task involves creating or building a component in Figma (even a single component), also load [figma-generate-library](../figma-generate-library/SKILL.md). It provides the component creation workflow — variable foundations, variant sets, design token bindings — that figma-use alone doesn't cover.

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.

1. console.log() is NOT returned — use return for output
2. 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.
3. Colors are 0–1 range (not 0–255): {r: 1, g: 0, b: 0} = red
4. Fills/strokes are read-only arrays — clone, modify, reassign
5. 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 " ". 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. See [Canonical text-edit recipe](references/gotchas.md#canonical-text-edit-recipe-font-load--await--mutate--return-ids).
6. 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)
7. setBoundVariableForPaint returns a NEW paint — must capture and reassign
8. createVariable accepts collection object or ID string (object preferred)
9. 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.

1. 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).
2. 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).
3. 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.
4. 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.
5. 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 does NOT work — it throws "Setting figma.currentPage is not supported" in use_figma. Always use the async method.

// 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

Call setCurrentPageAsync at most once per use_figma invocation — fan multi-page work out in parallel

One script must switch pages at most once. Never loop over figma.root.children and switch pages inside the loop.

If the work spans multiple pages, split it into N use_figma calls (one per target page) and emit them in parallel — a single assistant message containing N use_figma tool-use blocks. The harness runs them concurrently; each script sets currentPage exactly once.

> Explicit instruction: when fanning out, you MUST issue the N tool calls in one message. Do not send them across multiple turns. Do not await one before issuing the next. Sequential per-page calls are slower than the in-loop pattern this rule replaces and waste the entire benefit of splitting.

// AVOID — switches pages N times in one script, reloads the file each time
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  // ... touch this page ...
}

// PREFER — read-only discovery call to get page IDs, then in the NEXT message
// emit N parallel use_figma tool calls (one per page), each setting currentPage once.

Default to parallel fan-out for any multi-page work — reads and writes alike. See [gotchas.md → Set current page once per use_figma call](references/gotchas.md#set-current-page-once-per-use_figma-call--split-multi-page-work-into-parallel-calls) for the full rationale.

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") and Slides ("slides") have different sets of available node types — most design nodes are blocked in FigJam, and FigJam-only nodes are blocked in Slides.

Tell the editor from the URL: Design = figma.com/design/..., FigJam = figma.com/board/..., Slides = figma.com/slides/.... Confirm before assuming an API is available.

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, SlideGrid, InteractiveSlideElement, Webpage.

Available in Slides mode: Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Section, TextPath, Slide, SlideRow, SlideGrid, InteractiveSlideElement.

Blocked in Slides mode: Sticky, Connector, ShapeWithText, CodeBlock, Webpage, Page.

Design-only APIs (not just node types): figma.createPage() is available only in Design files (figma.com/design/...). In both FigJam (figma.com/board/...) and Slides (figma.com/slides/...) it throws TypeError: figma.createPage no such property 'createPage' on the figma global object. Do not emit figma.createPage() in FigJam or Slides workflows.

> Slides note: There is no dedicated read tool for Slides files yet. Use use_figma with read-only scripts for inspection (see Section 6 "Inspect first" pattern), and get_screenshot / await node.screenshot() for visual context. For Slides-specific API guidance, load the [figma-use-slides](../figma-use-slides/SKILL.md) skill.

5. Efficient APIs — Prefer These Over Verbose Alternatives

These APIs reduce boilerplate, eliminate ordering errors, and compress token output. Always prefer them over the verbose alternatives.

node.query(selector) — CSS-like node search

Find nodes within a subtree using CSS-like selectors. Replaces verbose findAll + filter loops.

// BEFORE — verbose traversal
const texts = frame.findAll(n => n.type === 'TEXT' && n.name === 'Title')

// AFTER — one-liner with query
const texts = frame.query('TEXT[name=Title]')

Selector syntax:

• Type: FRAME, TEXT, RECTANGLE, ELLIPSE, COMPONENT, INSTANCE, SECTION (case-insensitive)
• Attribute exact: [name=Card], [visible=true], [opacity=0.5]
• Attribute substring: [name*=art] (contains), [name^=Header] (starts-with), [name$=Nav] (ends-with)
• Dot-path traversal: [fills.0.type=SOLID], [fills.*.type=SOLID] (wildcard index)
• Instance matching: [mainComponent=nodeId], [mainComponent.name=Button]
• Combinators: FRAME > TEXT (direct child), FRAME TEXT (any descendant), A + B (adjacent sibling), A ~ B (general sibling)
• Pseudo-classes: :first-child, :last-child, :nth-child(2), :not(TYPE), :is(FRAME, RECTANGLE), :where(TEXT, ELLIPSE)
• Node ID: #nodeId or bare GUID
• Comma: TEXT, RECTANGLE (union)
• Wildcard: * (any type)

QueryResult methods: | Method | Description | |---|---| | .length | Number of matched nodes | | .first() | First matched node (or null) | | .last() | Last matched node (or null) | | .toArray() | Convert to regular array | | .each(fn) | Iterate with callback, returns this for chaining | | .map(fn) | Map to new array | | .filter(fn) | Filter to new QueryResult | | .values(keys) | Extract property values: .values(['name', 'x', 'y']) → [{name, x, y}, ...] | | .set(props) | Set properties on all matched nodes (see node.set() below) | | .query(selector) | Sub-query within matched nodes | | for...of | Iterable — works in for loops |

Scope: node.query() searches within that node's subtree. To search the whole page: figma.currentPage.query('...'). There is no global figma.query().

Examples:

// Recolor all text inside cards
figma.currentPage.query('FRAME[name^=Card] TEXT').set({
  fills: [{type: 'SOLID', color: {r: 0.2, g: 0.2, b: 0.8}}]
})

// Get names and positions of all frames
return figma.currentPage.query('FRAME').values(['name', 'x', 'y'])

// Find the first component named "Button"
const btn = figma.currentPage.query('COMPONENT[name=Button]').first()

// Find all instances of a specific component
figma.currentPage.query(`INSTANCE[mainComponent=${compId}]`)

// Find nodes with solid fills using dot-path traversal
figma.currentPage.query('[fills.0.type=SOLID]')

node.set(props) — batch property updates

Set multiple properties in one call. Returns this for chaining.

// BEFORE — one line per property
frame.opacity = 0.5
frame.cornerRadius = 8
frame.name = "Card"

// AFTER — single call
frame.set({ opacity: 0.5, cornerRadius: 8, name: "Card" })

Priority key ordering: layoutMode is always applied before other properties (like width/height) regardless of object key order. This prevents the common bug where resize() behaves differently depending on

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: thedesignproject
• Source: thedesignproject/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.