Figma Use

What This Skill Does

• The use_figma skill executes Java Script code within Figma files using the Plugin API.
• It allows agents to interact with and manipulate Figma designs programmatically.
• This skill is ideal for tasks requiring fine-grained control over Figma elements and properties.

When to Use

• Modify text properties of a Figma element.
• Change the color of a specific layer in Figma.
• Create new shapes or elements in a Figma file.
• Automate repetitive design tasks in Figma.
• Extract design data from Figma for analysis.
• Update design system components programmatically.

Key Features

• Executes Java Script code within Figma via the Plugin API.
• Supports asynchronous operations with top-level await.
• Automatically serializes return values as JSON.
• Provides access to the full Figma Plugin API surface.
• Integrates with design system workflows.
• Includes references for components, variables, and styles.

Manual Installation

Manual installation View Full Skill Content The complete markdown content that gets installeduse_figma — Figma Plugin API Skill

• Use use_figma MCP to execute Java Script 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

• Use return to send data back.
• The return value is JSON-serialized automatically (objects, arrays, strings, numbers).
• Do NOT call figma.close Plugin () or wrap code in an async IIFE — this is handled for you.
• Write plain Java Script 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. getPlugin Data () / setPlugin Data () are not supported in use_figma — do not use them. Use getSharedPlugin Data () / setSharedPlugin Data () 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.loadFont Async ({family, style}) Pages load incrementally — use await figma.setCurrentPage Async (page) to switch pages and load their content (see Page Rules below) setBoundVariableFor Paint returns a NEW paint — must capture and reassign create Variable accepts collection object or ID string (object preferred) layoutSizingHorizontal/Vertical = 'FILL' MUST be set AFTER parent.append Child (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.loadFont Async (...) without await, or figma.setCurrentPage Async (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.

2. Page Rules (Critical)

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

Switching pages

• Use await figma.setCurrentPage Async (page) to switch pages and load their content.
• The sync setter figma.current Page = page throws an error in use_figma runtimes.

// Switch to a specific page (loads its content) const target Page = figma.root.children.find ((p) => p.name === "My Page"); await figma.setCurrentPage Async (targetPage); // targetPage.children is now populated

// Iterate over all pages for (const page of figma.root.children) { await figma.setCurrentPage Async (page); // page.children is now loaded — read or modify them here }

Across script runs

figma.current Page 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.setCurrentPage Async (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 (editor Type "figma", the default). Fig Jam ("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 Workf