figma-use
**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 requires JavaScript execution in the Figma file context — e.g. create/edit/delete nodes, set up variables or tokens, build components and variants, modify auto-layout or fills, bind variables to properties, or inspect file structure programmatically.
thedesignproject · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add thedesignproject/agent-skills --skill figma-useAbout this skill
name: figma-use
description: "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 requires JavaScript execution in the Figma file context — e.g. create/edit/delete nodes, set up variables or tokens, build components and variants, modify auto-layout or fills, bind variables to properties, or inspect file structure programmatically."
disable-model-invocation: false
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. 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. 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 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
returnto send data back. The return value is JSON-serialized automatically (objects, arrays, strings, numbers). Do NOT callfigma.closePlugin()or wrap code in an async IIFE — this is handled for you. - Write plain JavaScript with top-level
awaitandreturn. Code is automatically wrapped in an async context. Do NOT wrap in(async () => { ... })(). figma.notify()throws "not implemented" — never use it 3a.getPluginData()/setPluginData()are not supported inuse_figma— do not use them. UsegetSharedPluginData()/setSharedPluginData()instead (these ARE supported), or track node IDs by returning them and passing them to subsequent calls.console.log()is NOT returned — usereturnfor output- Work incrementally in small steps. Break large operations into multiple
use_figmacalls. 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
- Every text edit follows the canonical recipe: load font →
await→ mutate → return affected node IDs. Skipping the load throwsCannot write to node with unloaded font "<family> <style>". The rule covers more thancharacters— it applies to any operation on nodes with unloaded fonts (appendChild,insertChild,setBoundVariable,setExplicitVariableModeForCollection,setValueForMode,findAllcallbacks touching text). When mutating existing text, load the node's current fonts viagetStyledTextSegments(['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. Useawait figma.listAvailableFontsAsync()first if the style string is unverified. See Canonical text-edit recipe. - Pages load incrementally — use
await figma.setCurrentPageAsync(page)to switch pages and load their content. The sync setterfigma.currentPage = pagedoes NOT work and will throw (see Page Rules below) setBoundVariableForPaintreturns a NEW paint — must capture and reassigncreateVariableaccepts collection object or ID string (object preferred)layoutSizingHorizontal/Verticalis value-restricted by structural context —FIXEDalways works,HUGandFILLdo 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 setHUG/FILL— a newly-created or unparented node can't satisfy the rule yet. The property itself exists on everySceneNode; the error is value-rejection, not "no such property". See Gotchas. 12a. Use auto-layout for containers that hold related children. When children have a structural relat