1# Gotchas & Common Mistakes
2 
3> Part of the [use_figma skill](../SKILL.md). Every known pitfall with WRONG/CORRECT code examples.
4 
5## Contents
6 
7- Component properties and variant creation pitfalls
8- Paint, color, and variable binding pitfalls
9- Page context and plugin lifecycle pitfalls
10- Auto Layout and sizing order pitfalls (including HUG/FILL interactions)
11- Variant layout and geometry pitfalls
12- Variable scopes and mode pitfalls
13- Node cleanup and empty-fill pitfalls
14- detachInstance() and node ID invalidation
15 
16 
17## New nodes default to (0,0) and overlap existing content
18 
19Every `figma.create*()` call places the node at position (0,0). If you append multiple nodes directly to the page, they all stack on top of each other and on top of any existing content.
20 
21**This only matters for nodes appended directly to the page** (i.e., top-level nodes). Nodes appended as children of other frames, components, or auto-layout containers are positioned by their parent — don't scan for overlaps when nesting nodes.
22 
23```js
24// WRONG — top-level node lands at (0,0), overlapping existing page content
25const frame = figma.createFrame()
26frame.name = "My New Frame"
27frame.resize(400, 300)
28figma.currentPage.appendChild(frame)
29 
30// CORRECT — find existing content bounds and place the new top-level node to the right
31const page = figma.currentPage
32let maxX = 0
33for (const child of page.children) {
34  const right = child.x + child.width
35  if (right > maxX) maxX = right
36}
37const frame = figma.createFrame()
38frame.name = "My New Frame"
39frame.resize(400, 300)
40figma.currentPage.appendChild(frame)
41frame.x = maxX + 100  // 100px gap from rightmost existing content
42frame.y = 0
43 
44// NOT NEEDED — child nodes inside a parent don't need overlap scanning
45const card = figma.createFrame()
46card.layoutMode = 'VERTICAL'
47const label = figma.createText()
48card.appendChild(label)  // positioned by auto-layout, no x/y needed
49```
50 
51## `addComponentProperty` returns a string key, not an object — never hardcode or guess it
52 
53Figma generates the property key dynamically (e.g. `"label#4:0"`). The suffix is unpredictable. Always capture and use the return value directly.
54 
55```js
56// WRONG — guessing / hardcoding the key
57comp.addComponentProperty('label', 'TEXT', 'Button')
58labelNode.componentPropertyReferences = { characters: 'label#0:1' }  // Error: key not found
59 
60// WRONG — treating the return value as an object
61const result = comp.addComponentProperty('Label', 'TEXT', 'Button')
62const propKey = Object.keys(result)[0]  // BUG: returns '0' (first char index of string!)
63labelNode.componentPropertyReferences = { characters: propKey }  // Error: property '0' not found
64 
65// CORRECT — the return value IS the key string, use it directly
66const propKey = comp.addComponentProperty('Label', 'TEXT', 'Button')
67// propKey === "label#4:0" (exact value varies; never assume it)
68labelNode.componentPropertyReferences = { characters: propKey }
69```
70 
71The same applies to `COMPONENT_SET` nodes — `addComponentProperty` always returns the property key as a string.
72 
73## MUST return ALL created/mutated node IDs
74 
75Every script that creates or mutates nodes on the canvas must track and return all affected node IDs in the return value. Without these IDs, subsequent calls cannot reference, validate, or clean up those nodes.
76 
77```js
78// WRONG — only returns the parent frame ID, loses track of children
79const frame = figma.createFrame()
80const rect = figma.createRectangle()
81const text = figma.createText()
82frame.appendChild(rect)
83frame.appendChild(text)
84return { nodeId: frame.id }
85 
86// CORRECT — returns all created node IDs in a structured response
87const frame = figma.createFrame()
88const rect = figma.createRectangle()
89const text = figma.createText()
90frame.appendChild(rect)
91frame.appendChild(text)
92return {
93  createdNodeIds: [frame.id, rect.id, text.id],
94  rootNodeId: frame.id
95}
96 
97// CORRECT — when mutating existing nodes, return those IDs too
98const nodes = figma.currentPage.findAll(n => n.name === 'Card')
99for (const n of nodes) {
100  n.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]
101}
102return {
103  mutatedNodeIds: nodes.map(n => n.id),
104  count: nodes.length
105}
106```
107 
108## Colors are 0–1 range
109 
110```js
111// WRONG — will throw validation error (ZeroToOne enforced)
112node.fills = [{ type: 'SOLID', color: { r: 255, g: 0, b: 0 } }]
113 
114// CORRECT
115node.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]
116```
117 
118## Fills/strokes are immutable arrays
119 
120```js
121// WRONG — modifying in place does nothing
122node.fills[0].color = { r: 1, g: 0, b: 0 }
123 
124// CORRECT — clone, modify, reassign
125const fills = JSON.parse(JSON.stringify(node.fills))
126fills[0].color = { r: 1, g: 0, b: 0 }
127node.fills = fills
128```
129 
130## setBoundVariableForPaint returns a NEW paint
131 
132```js
133// WRONG — ignoring return value
134figma.variables.setBoundVariableForPaint(paint, "color", colorVar)
135node.fills = [paint]  // paint is unchanged!
136 
137// CORRECT — capture the returned new paint
138const boundPaint = figma.variables.setBoundVariableForPaint(paint, "color", colorVar)
139node.fills = [boundPaint]
140```
141 
142## Variable collection starts with 1 mode
143 
144```js
145// A new collection already has one mode — rename it, don't try to add first
146const collection = figma.variables.createVariableCollection("Colors")
147// collection.modes = [{ modeId: "...", name: "Mode 1" }]
148collection.renameMode(collection.modes[0].modeId, "Light")
149const darkModeId = collection.addMode("Dark")
150```
151 
152## combineAsVariants requires ComponentNodes
153 
154```js
155// WRONG — passing frames
156const f1 = figma.createFrame()
157figma.combineAsVariants([f1], figma.currentPage) // Error!
158 
159// CORRECT — passing components
160const c1 = figma.createComponent()
161c1.name = "variant=primary, size=md"
162const c2 = figma.createComponent()
163c2.name = "variant=secondary, size=md"
164figma.combineAsVariants([c1, c2], figma.currentPage)
165```
166 
167## Page switching: sync setter throws
168 
169The sync setter `figma.currentPage = page` **throws an error** in `use_figma` runtimes (MCP, evals, assistant). Use `await figma.setCurrentPageAsync(page)` instead — it switches the page and loads its content.
170 
171```js
172// WRONG — throws "Setting figma.currentPage is not supported in this runtime"
173figma.currentPage = targetPage
174 
175// CORRECT — async method switches and loads content
176await figma.setCurrentPageAsync(targetPage)
177```
178 
179## `get_metadata` only sees one page — use `use_figma` to discover all pages
180 
181A Figma file can have multiple pages (canvas nodes). `get_metadata` operates on a single node/page — it cannot scan the entire document. To discover all pages and their top-level contents, use `use_figma`:
182 
183```js
184// WRONG — calling get_metadata with the file root or expecting it to list all pages
185// get_metadata only returns the subtree of the node you pass it
186 
187// CORRECT — use use_figma to list pages, then inspect each one
188const pages = figma.root.children.map(p => `${p.name} id=${p.id} children=${p.children.length}`);
189return pages.join('\n');
190```
191 
192Icons, variables, and components may live on pages other than the first. Always enumerate all pages before concluding that the file has no existing assets.
193 
194## Never use figma.notify()
195 
196```js
197// WRONG — throws "not implemented" error
198figma.notify("Done!")
199 
200// CORRECT — return a value to send data back to the agent
201return "Done!"
202```
203 
204## `getPluginData()` / `setPluginData()` are not supported
205 
206These APIs are not available in the `use_figma` runtime. Use `getSharedPluginData()` / `setSharedPluginData()` instead (these ARE supported), or track nodes by returning IDs.
207 
208```js
209// WRONG — not supported in use_figma
210node.setPluginData('my_key', 'my_value')
211const val = node.getPluginData('my_key')
212 
213// CORRECT — use shared plugin data (requires a namespace)
214node.setSharedPluginData('my_namespace', 'my_key', 'my_value')
215const val = node.getSharedPluginData('my_namespace', 'my_key')
216 
217// ALSO CORRECT — return node IDs and track them across calls
218const rect = figma.createRectangle()
219return { nodeId: rect.id }
220// Then pass nodeId as a string literal in the next use_figma call
221```
222 
223## Script must always return a value
224 
225```js
226// WRONG — no return, caller gets no useful response
227figma.createRectangle()
228 
229// CORRECT — return a result (objects are auto-serialized, errors are auto-captured)
230const rect = figma.createRectangle()
231return { nodeId: rect.id }
232```
233 
234## setBoundVariable for paint fields only works on SOLID paints
235 
236```js
237// Only SOLID paint type supports color variable binding
238// Gradient paints, image paints, etc. will throw
239const solidPaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }
240const bound = figma.variables.setBoundVariableForPaint(solidPaint, "color", colorVar)
241```
242 
243## Explicit variable modes must be set per component
244 
245```js
246// WRONG — all variants render with the default (first) mode
247const colorCollection = figma.variables.createVariableCollection("Colors")
248// ... create variables and modes ...
249// Components all show the first mode's values by default!
250 
251// CORRECT — set explicit mode on each component to get variant-specific values
252component.setExplicitVariableModeForCollection(colorCollection, targetModeId)
253```
254 
255## `TextStyle.setBoundVariable` is not available in headless use_figma
256 
257`setBoundVariable` exists on `TextStyle` in the typed API but is **not available** when running scripts through `use_figma` (MCP, headless assistant mode). Calling it will throw `"not a function"`.
258 
259```js
260// WRONG — throws "not a function" in use_figma / headless
261const ts = figma.createTextStyle()
262ts.setBoundVariable("fontSize", fontSizeVar)
263 
264// CORRECT (headless) — set raw values; bind variables interactively in Figma later
265const ts = figma.createTextStyle()
266ts.fontSize = 24
267```
268 
269This only affects `TextStyle`. Variable binding on **nodes** (`node.setBoundVariable(...)`) and on **paint objects** (`figma.variables.setBoundVariableForPaint(...)`) still works in headless mode as expected.
270 
271If live variable binding on text styles is required, create the styles with raw values via `use_figma`, then bind variables interactively through the Figma Styles panel or a full interactive plugin.
272 
273## `lineHeight` and `letterSpacing` must be objects, not bare numbers
274 
275```js
276// WRONG — throws or silently does nothing
277style.lineHeight = 1.5
278style.lineHeight = 24
279style.letterSpacing = 0
280 
281// CORRECT
282style.lineHeight = { unit: "AUTO" }                    // auto/intrinsic
283style.lineHeight = { value: 24, unit: "PIXELS" }       // fixed pixel height
284style.lineHeight = { value: 150, unit: "PERCENT" }     // percentage of font size
285 
286style.letterSpacing = { value: 0, unit: "PIXELS" }     // no tracking
287style.letterSpacing = { value: -0.5, unit: "PIXELS" }  // tight
288style.letterSpacing = { value: 5, unit: "PERCENT" }    // percent-based
289```
290 
291This applies to both `TextStyle` and `TextNode` properties. The same rule applies inside `use_figma`, interactive plugins, and any other plugin API context.
292 
293## Font style names are file-dependent — probe before assuming
294 
295Font style names vary per provider and per Figma file. `"SemiBold"` and `"Semi Bold"` are different strings. Loading a font with the wrong style string **throws silently or errors** — there is no canonical list.
296 
297```js
298// WRONG — guessing style names
299await figma.loadFontAsync({ family: "Inter", style: "SemiBold" }) // may throw
300 
301// CORRECT — probe which style names are available
302const candidates = ["SemiBold", "Semi Bold", "Semibold"]
303for (const style of candidates) {
304  try {
305    await figma.loadFontAsync({ family: "Inter", style })
306    // capture the one that works
307    break
308  } catch (_) {}
309}
310```
311 
312When building a type ramp script, always verify font styles against the target file before hardcoding them.
313 
314## combineAsVariants does NOT auto-layout in headless mode
315 
316```js
317// WRONG — all variants stack at position (0, 0), resulting in a tiny ComponentSet
318const components = [comp1, comp2, comp3]
319const cs = figma.combineAsVariants(components, figma.currentPage)
320// cs.width/height will be the size of a SINGLE variant!
321 
322// CORRECT — manually layout children in a grid after combining
323const cs = figma.combineAsVariants(components, figma.currentPage)
324const colWidth = 120
325const rowHeight = 56
326cs.children.forEach((child, i) => {
327  const col = i % numCols
328  const row = Math.floor(i / numCols)
329  child.x = col * colWidth
330  child.y = row * rowHeight
331})
332// CRITICAL: resize from actual child bounds, not formula — formula errors leave variants outside the boundary
333let maxX = 0, maxY = 0
334for (const child of cs.children) {
335  maxX = Math.max(maxX, child.x + child.width)
336  maxY = Math.max(maxY, child.y + child.height)
337}
338cs.resizeWithoutConstraints(maxX + 40, maxY + 40)
339```
340 
341## COLOR variable values use {r, g, b, a} (with alpha)
342 
343```js
344// Paint colors use {r, g, b} (no alpha — opacity is a separate paint property)
345node.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]
346 
347// But COLOR variable values use {r, g, b, a} — alpha maps to paint opacity
348const colorVar = figma.variables.createVariable("bg", collection, "COLOR")
349colorVar.setValueForMode(modeId, { r: 1, g: 0, b: 0, a: 1 })  // opaque red
350colorVar.setValueForMode(modeId, { r: 0, g: 0, b: 0, a: 0 })  // fully transparent
351 
352// ⚠️ Don't confuse: {r, g, b} for paint colors vs {r, g, b, a} for variable values
353```
354 
355## `layoutSizingVertical`/`layoutSizingHorizontal` = `'FILL'` requires auto-layout parent FIRST
356 
357```js
358// WRONG — setting FILL before the node is a child of an auto-layout frame
359const child = figma.createFrame()
360child.layoutSizingVertical = 'FILL'  // ERROR: "FILL can only be set on children of auto-layout frames"
361parent.appendChild(child)
362 
363// CORRECT — append to auto-layout parent FIRST, then set FILL
364const child = figma.createFrame()
365parent.appendChild(child)            // parent must have layoutMode set
366child.layoutSizingVertical = 'FILL'  // Works!
367```
368 
369## HUG parents collapse FILL children
370 
371A `HUG` parent cannot give `FILL` children meaningful size. If children have `layoutSizingHorizontal = "FILL"` but the parent is `"HUG"`, the children collapse to minimum size. The parent must be `"FILL"` or `"FIXED"` for FILL children to expand. This is a common cause of truncated text in select fields, inputs, and action rows.
372 
373```js
374// WRONG — parent hugs, so FILL children get zero extra space
375const parent = figma.createFrame()
376parent.layoutMode = 'HORIZONTAL'
377parent.layoutSizingHorizontal = 'HUG'
378const child = figma.createFrame()
379parent.appendChild(child)
380child.layoutSizingHorizontal = 'FILL'  // collapses to min size!
381 
382// CORRECT — parent must be FIXED or FILL for FILL children to expand
383const parent = figma.createFrame()
384parent.layoutMode = 'HORIZONTAL'
385parent.resize(400, 50)
386parent.layoutSizingHorizontal = 'FIXED'  // or 'FILL' if inside another auto-layout
387const child = figma.createFrame()
388parent.appendChild(child)
389child.layoutSizingHorizontal = 'FILL'  // expands to fill remaining 400px
390```
391 
392## `layoutGrow` with a hugging parent causes content compression
393 
394```js
395// WRONG — layoutGrow on a child when parent has primaryAxisSizingMode='AUTO' (hug)
396// causes the child to SHRINK below its natural size instead of expanding
397const parent = figma.createComponent()
398parent.layoutMode = 'VERTICAL'
399parent.primaryAxisSizingMode = 'AUTO'  // hug contents
400const content = figma.createFrame()
401content.layoutMode = 'VERTICAL'
402content.primaryAxisSizingMode = 'AUTO'
403parent.appendChild(content)
404content.layoutGrow = 1  // BUG: content compresses, children hidden!
405 
406// CORRECT — only use layoutGrow when parent has FIXED sizing with extra space
407content.layoutGrow = 0  // let content take its natural size
408// OR: set parent to FIXED sizing first
409parent.primaryAxisSizingMode = 'FIXED'
410parent.resizeWithoutConstraints(300, 500)
411content.layoutGrow = 1  // NOW it correctly fills remaining space
412```
413 
414## `resize()` resets `primaryAxisSizingMode` and `counterAxisSizingMode` to FIXED
415 
416`resize(w, h)` silently resets **both** sizing modes to `FIXED`. If you call it after setting `HUG`, the frame locks to the exact pixel value you passed — even a throwaway like `1`.
417 
418```js
419// WRONG — resize() after setting sizing mode overwrites it