renfei-design/design-jarvis/figma-use

use_figma — Figma Plugin API Skill

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 hifi-design. Its Workflow B section covers discovering design system components via search_design_system, importing them, and assembling screens incrementally. Both skills work together: this one for the Plugin 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.

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. Font MUST be loaded before any text operation: await figma.loadFontAsync({family, style})
6. Pages load incrementally — use await figma.setCurrentPageAsync(page) to switch pages and load their content (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 = 'FILL'` MUST be set AFTER `parent.appendChild(child)` — setting before append throws. Same applies to 'HUG' on non-auto-layout nodes.
10. 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.
11. 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.
12. 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.
13. 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.
14. `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.

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 throws an error in use_figma runtimes.

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

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

4a. Performance & Batching (Token Discipline)

These rules previously lived in _shared-context.md and apply to every screen-building call.

Batch aggressively

• Put as much work as possible into each `use_figma` call. A single script that creates a frame, imports 3 components, sets their text, and positions them is far better than 4 separate calls.
• Create the entire section in one call — frame + children + text + properties. Don't create empty frames then fill them in subsequent calls.
• Batch text updates — if setting text on 5 nodes, do it in one use_figma script with a loop, not 5 separate calls.

Minimize call count

• Target: 2–4 `use_figma` calls per screen. One for the root + shell, one for each major section. Avoid going above 6 calls per screen.
• Use `get_screenshot` for validation only at milestones — not after every call. Screenshot the full screen once after all sections are built. Never poll get_screenshot in a loop.
• Skip `search_design_system` if you already know the component. Cache component keys from earlier calls. Only search when you need a component you haven't used before.

Token-efficient queries (G7)

• Prefer node-scoped `get_metadata` over whole-page metadata: pass a specific nodeId instead of letting it traverse the entire page.
• Cache component keys returned by search_design_system and reuse — never re-search the same family in the same task.
• Avoid `get_screenshot` as polling. It returns large image payloads. Use it once at major milestones and rely on returned node IDs for intermediate validation.
• Read only what you'll use. If you only need a frame's name and dimensions, write a use_figma script that returns exactly those fields — don't dump the whole node JSON.

Font and color shortcuts

• Fonts — inspect the current file, then load every font and style needed for the batch before changing text.
• Colors are 0–1 range — {r: 0.067, g: 0.471, b: 0.396} for brand teal, not {r: 17, g: 120, b: 101}.
• Set FILL/HUG AFTER appendChild — this is the #1 cause of failed scripts.

Icon discovery

• Reuse the active project's icon library when one is configured. If none exists, use simple semantic shapes or text labels instead of inventing product-specific icons.
• Use `search_design_system` only for icons not in the catalog.

Prefer Workflow A for new screens

• Default to HTML capture for any new screen design. It produces a complete screen in 1 capture call, with no component lookup overhead.
• Only use Workflow B (component-linked) when the user explicitly requests it, or when the design must be editable in Figma with real auto-layout and design system bindings.

5. Incremental Workflow (How to Avoid Bugs)

The most common cause of bugs is trying to do too much in a single use_figma call. Work in small steps and validate after each one.

The pattern

1. Inspect first. Before creating anything, run a read-only use_figma to discover what already exists in the file — pages, components, variables, naming conventions. Match what's there.
2. Do one thing per call. Create variables in one call, create components in the next, compose layouts in another. Don't try to build an entire screen in one script.
3. Return IDs from every call. Always return created node IDs, variable IDs, collection IDs as objects (e.g. return { createdNodeIds: [...] }). You'll need these as inputs to subsequent calls.
4. Validate after each step. Use get_metadata to verify structure (counts, names, hierarchy, positions). Use get_screenshot after major milestones to catch visual issues.
5. Fix before moving on. If validation reveals a problem, fix it before proceeding to the next step. Don't build on a broken foundation.

Suggested step order for complex tasks

Step 1: Inspect file — discover existing pages, components, variables, conventions
Step 2: Create tokens/variables (if needed)
       → validate with get_metadata
Step 3: Create individual components
       → validate with get_metadata + get_screenshot
Step 4: Compose layouts from component instances
       → validate with get_screenshot
Step 5: Final verification

What to validate at each step