1# Figma Plugin API Reference
2 
3> Part of the [use_figma skill](../SKILL.md). What works and what doesn't in the `use_figma` environment.
4 
5## Contents
6 
7- Node Creation
8- Grouping and Boolean Operations
9- Library Imports
10- Variables API
11- Core Properties
12- Node Manipulation
13- Descriptions and Documentation Links
14- SVG and Images
15- Utilities and Plugin Lifecycle
16- Node Traversal
17- Unsupported APIs
18 
19 
20## Node Creation (Design Mode)
21 
22```js
23figma.createRectangle()
24figma.createFrame()
25figma.createComponent()         // Creates a ComponentNode
26figma.createText()
27figma.createEllipse()
28figma.createStar()
29figma.createLine()
30figma.createVector()
31figma.createPolygon()
32figma.createBooleanOperation()
33figma.createSlice()
34figma.createPage()              // Page node can be created, but child persistence is limited in headless mode
35figma.createSection()
36figma.createTextPath()
37```
38 
39## Grouping & Boolean Operations
40 
41```js
42figma.group(nodes, parent, index?)              // Group nodes
43figma.flatten(nodes, parent?, index?)           // Flatten to vector
44figma.union(nodes, parent?, index?)             // Boolean union
45figma.subtract(nodes, parent?, index?)          // Boolean subtract
46figma.intersect(nodes, parent?, index?)         // Boolean intersect
47figma.exclude(nodes, parent?, index?)           // Boolean exclude
48figma.combineAsVariants(components, parent?)    // Combine ComponentNodes into ComponentSet (Design/Sites only)
49```
50 
51## Library Component Import
52 
53These methods import components from **team libraries** (not the same file you're working in). For components in the current file, use `use_figma` with `figma.getNodeByIdAsync()` or `findOne()`/`findAll()` to locate them directly.
54 
55```js
56// Import a published component from a team library by key
57const comp = await figma.importComponentByKeyAsync("COMPONENT_KEY")
58const instance = comp.createInstance()
59 
60// Import a published component set from a team library by key
61const compSet = await figma.importComponentSetByKeyAsync("COMPONENT_SET_KEY")
62const variant =
63  compSet.children.find((c) => c.type === "COMPONENT" && c.name.includes("size=md")) ||
64  compSet.defaultVariant
65const variantInstance = variant.createInstance()
66```
67 
68## Library Style Import (Team Libraries)
69 
70These methods import styles from **team libraries** (not the same file). For styles in the current file, use `figma.getLocalPaintStyles()`, `figma.getLocalTextStyles()`, etc.
71 
72```js
73// Import a published style from a team library by key
74const style = await figma.importStyleByKeyAsync("STYLE_KEY")
75 
76// Apply the imported style to a node
77await node.setFillStyleIdAsync(style.id)    // for PaintStyle as fill
78await node.setStrokeStyleIdAsync(style.id)  // for PaintStyle as stroke
79await node.setTextStyleIdAsync(style.id)    // for TextStyle
80await node.setEffectStyleIdAsync(style.id)  // for EffectStyle
81await node.setGridStyleIdAsync(style.id)    // for GridStyle
82```
83 
84## Library Variable Import (Team Libraries)
85 
86This imports variables from **team libraries** (not the same file). For variables in the current file, use `figma.variables.getLocalVariablesAsync()` or `figma.variables.getVariableByIdAsync()`.
87 
88```js
89// Import a published variable from a team library by key
90const variable = await figma.variables.importVariableByKeyAsync("VARIABLE_KEY")
91 
92// Bind the imported variable to node properties
93node.setBoundVariable("width", variable)           // FLOAT variable
94 
95// Bind to fills/strokes (COLOR variable) — returns a NEW paint, must capture it
96const newPaint = figma.variables.setBoundVariableForPaint(paintCopy, "color", variable)
97node.fills = [newPaint]
98```
99 
100## Variables API
101 
102```js
103// Collections
104const collection = figma.variables.createVariableCollection("Name")
105collection.name                           // Get/set name
106collection.modes                          // Array of {modeId, name} — starts with 1 mode
107collection.addMode("Dark")               // Returns new modeId string
108collection.renameMode(modeId, "Light")
109 
110// Variables
111const variable = figma.variables.createVariable("name", collection, "COLOR")
112//                                                       ^ must be a collection object (passing an ID string is deprecated)
113// resolvedType: "COLOR" | "FLOAT" | "STRING" | "BOOLEAN"
114variable.setValueForMode(modeId, value)
115 
116// Scopes — controls where variable appears in property pickers
117variable.scopes = ["FRAME_FILL", "SHAPE_FILL"]   // only fill pickers
118variable.scopes = ["TEXT_FILL"]                    // only text color picker
119variable.scopes = ["STROKE_COLOR"]                 // only stroke picker
120variable.scopes = []                               // hidden from all pickers (use for primitives)
121// All valid scope values:
122//   ALL_SCOPES, TEXT_CONTENT, CORNER_RADIUS, WIDTH_HEIGHT, GAP,
123//   ALL_FILLS, FRAME_FILL, SHAPE_FILL, TEXT_FILL,
124//   STROKE_COLOR, STROKE_FLOAT, EFFECT_FLOAT, EFFECT_COLOR,
125//   OPACITY, FONT_FAMILY, FONT_STYLE, FONT_WEIGHT, FONT_SIZE,
126//   LINE_HEIGHT, LETTER_SPACING, PARAGRAPH_SPACING, PARAGRAPH_INDENT
127 
128// Querying (always use the Async variants — sync versions are deprecated)
129await figma.variables.getVariableByIdAsync(id)
130await figma.variables.getLocalVariablesAsync(resolvedType?)
131await figma.variables.getVariableCollectionByIdAsync(id)
132await figma.variables.getLocalVariableCollectionsAsync()
133 
134// Binding variables to paints (COLOR variables)
135const newPaint = figma.variables.setBoundVariableForPaint(paintCopy, "color", variable)
136// ⚠️ Returns a NEW paint — must capture return value!
137node.fills = [newPaint]
138 
139// Binding variables to effects (COLOR/FLOAT variables)
140const newEffect = figma.variables.setBoundVariableForEffect(effectCopy, field, variable)
141// field for shadows: "color" (COLOR), "radius" | "spread" | "offsetX" | "offsetY" (FLOAT)
142// field for blurs: "radius" (FLOAT)
143// ⚠️ Returns a NEW effect — must capture return value!
144node.effects = [newEffect]
145 
146// Binding variables to layout grids (FLOAT variables)
147const newGrid = figma.variables.setBoundVariableForLayoutGrid(gridCopy, field, variable)
148// field: "sectionSize" | "offset" | "count" | "gutterSize"
149// ⚠️ Returns a NEW layout grid — must capture return value!
150node.layoutGrids = [newGrid]
151 
152// Binding variables to node properties (FLOAT/STRING/BOOLEAN)
153// Layout & sizing (FLOAT):
154node.setBoundVariable("width", variable)
155node.setBoundVariable("height", variable)
156node.setBoundVariable("minWidth", variable)
157node.setBoundVariable("maxWidth", variable)
158node.setBoundVariable("minHeight", variable)
159node.setBoundVariable("maxHeight", variable)
160node.setBoundVariable("paddingLeft", variable)
161node.setBoundVariable("paddingRight", variable)
162node.setBoundVariable("paddingTop", variable)
163node.setBoundVariable("paddingBottom", variable)
164node.setBoundVariable("itemSpacing", variable)
165node.setBoundVariable("counterAxisSpacing", variable)
166// Corner radii (FLOAT) — use individual corners, NOT cornerRadius:
167node.setBoundVariable("topLeftRadius", variable)
168node.setBoundVariable("topRightRadius", variable)
169node.setBoundVariable("bottomLeftRadius", variable)
170node.setBoundVariable("bottomRightRadius", variable)
171// Other (FLOAT):
172node.setBoundVariable("opacity", variable)
173node.setBoundVariable("strokeWeight", variable)
174// ⚠️ fontSize, fontWeight, lineHeight are NOT bindable via setBoundVariable
175// — set these directly as values on text nodes
176 
177// Aliases
178figma.variables.createVariableAlias(variable)
179 
180// Explicit modes — CRITICAL for variant components
181node.setExplicitVariableModeForCollection(collection, modeId)  // pass collection object, NOT an ID string
182// Without this, all nodes use the default (first) mode of the collection
183```
184 
185## Core Properties
186 
187```js
188figma.root                      // DocumentNode
189figma.currentPage               // Current page (read-only in use_figma; sync setter throws)
190figma.setCurrentPageAsync(page) // Switch page and load its content (MUST await)
191figma.fileKey                   // File key string
192figma.mixed                     // Mixed sentinel value
193```
194 
195## Node Manipulation
196 
197```js
198// Fills & Strokes (read-only arrays — must clone)
199node.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]
200node.strokes = [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }]
201node.strokeWeight = 1
202node.strokeAlign = 'INSIDE'             // 'INSIDE' | 'CENTER' | 'OUTSIDE'
203 
204// Effects
205node.effects = [{ type: 'DROP_SHADOW', color: {r:0,g:0,b:0,a:0.25}, offset:{x:0,y:4}, radius:4, visible:true }]
206 
207// Layout
208node.layoutMode = 'HORIZONTAL'          // 'NONE' | 'HORIZONTAL' | 'VERTICAL'
209node.primaryAxisAlignItems = 'CENTER'    // 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN'
210node.counterAxisAlignItems = 'CENTER'    // 'MIN' | 'CENTER' | 'MAX' | 'BASELINE'
211node.paddingLeft = 8
212node.paddingRight = 8
213node.paddingTop = 4
214node.paddingBottom = 4
215node.itemSpacing = 4
216node.layoutSizingHorizontal = 'HUG'     // 'FIXED' | 'HUG' | 'FILL'
217node.layoutSizingVertical = 'HUG'       // 'FIXED' | 'HUG' | 'FILL'
218 
219// Sizing
220node.resize(width, height)                     // ⚠️ Resets sizing modes to FIXED
221node.resizeWithoutConstraints(width, height)   // Doesn't affect constraints
222 
223// Corner radius
224node.cornerRadius = 8
225 
226// Visibility & Opacity
227node.visible = true
228node.opacity = 0.5
229 
230// Naming & Hierarchy
231node.name = "My Node"
232parent.appendChild(child)
233parent.insertChild(index, child)
234node.remove()
235```
236 
237## Descriptions & Documentation Links
238 
239```js
240// Description — plain text, shown in Figma's component panel
241node.description = "A short summary of this component's purpose and usage."
242 
243// Documentation links — array of {uri, label} shown as clickable links
244componentSet.documentationLinks = [
245  { uri: "https://example.com/docs", label: "Component Docs" }
246]
247// ⚠️ uri MUST be a valid URL (https://...) — relative paths will throw
248```
249 
250## SVG Import
251 
252```js
253const svgNode = figma.createNodeFromSvg('<svg>...</svg>')
254```
255 
256## Images
257 
258```js
259const image = figma.createImage(uint8Array)
260node.fills = [{ type: 'IMAGE', scaleMode: 'FILL', imageHash: image.hash }]
261```
262 
263## Utilities
264 
265```js
266figma.base64Encode(uint8Array)     // Uint8Array → base64 string
267figma.base64Decode(base64String)   // base64 string → Uint8Array
268figma.createComponentFromNode(node) // Convert existing node to component (Design/Sites only)
269```
270 
271## Plugin Lifecycle
272 
273Scripts are automatically wrapped in an async IIFE with error handling. Use `return` to send data back:
274 
275```js
276return { nodeId: frame.id }     // Return object — auto-serialized to JSON
277return "success message"        // Return string
278// Errors are auto-captured — no try/catch or closePlugin needed
279```
280 
281## Node Traversal
282 
283```js
284node.findAll(pred?)            // Find all descendants matching predicate
285node.findOne(pred?)            // Find first descendant matching predicate
286node.findChildren(pred?)       // Find direct children matching predicate
287node.findChild(pred?)          // Find first direct child matching predicate
288node.children                  // Direct children array
289node.parent                    // Parent node
290```
291 
292---
293 
294## What Does NOT Work
295 
296| API | Status |
297|-----|--------|
298| `figma.notify()` | **Throws "not implemented"** — most common mistake |
299| `figma.showUI()` | No-op (silently ignored) |
300| `figma.openExternal()` | No-op (silently ignored) |
301| `figma.listAvailableFontsAsync()` | Not implemented |
302| `figma.loadAllPagesAsync()` | Not implemented |
303| `figma.variables.extendLibraryCollectionByKeyAsync()` | Not implemented |
304| `figma.teamLibrary.*` | Not implemented (requires LiveGraph) |
305