1# Plugin API Patterns
2 
3> Part of the [use_figma skill](../SKILL.md). Quick reference for common Figma Plugin API operations.
4 
5## Contents
6 
7- Execution Basics
8- Creating Nodes
9- Fills and Strokes
10- Auto Layout
11- Effects
12- Opacity and Blend Modes
13- Corner Radius and Clipping
14- Grouping and Organization
15- Components and Variants
16- Styles
17- Cloning, Finding Nodes, and Grids
18- Constraints and Viewport
19 
20 
21## Execution Basics
22 
23### Page Context
24 
25Page context resets between `use_figma` calls — `figma.currentPage` always starts on the first page. Use `await figma.setCurrentPageAsync(page)` at the start of each invocation to switch to the correct page.
26 
27```javascript
28const targetPage = figma.root.children.find(p => p.name === "My Page");
29await figma.setCurrentPageAsync(targetPage);
30// targetPage.children is now populated
31```
32 
33### Returning Results
34 
35Scripts are automatically wrapped in an async IIFE with error handling. Just write plain JS and use `return` to send data back to the agent:
36 
37```javascript
38// Return an object — auto-serialized to JSON
39return { nodeId: frame.id, count: 5 }
40 
41// Return a string
42return "Created 3 components"
43```
44 
45Errors are automatically captured — no try/catch needed. `figma.notify()` does **not** exist. Return all information via the `return` value.
46 
47### Working Incrementally
48 
49Don't build an entire screen in one call. Break work into small steps:
501. Create tokens/variables
512. Create text styles
523. Build individual components
534. Compose sections
545. Assemble screens
55 
56Verify structure with `get_metadata` between steps. Use `get_screenshot` after each major creation milestone to catch visual problems early.
57 
58## Creating Nodes
59 
60### Frames
61 
62```javascript
63const frame = figma.createFrame();
64frame.name = "Container";
65frame.resize(1440, 900);
66frame.x = 0;
67frame.y = 0;
68frame.fills = [{ type: "SOLID", color: { r: 0.98, g: 0.98, b: 0.99 } }];
69```
70 
71### Text
72 
73```javascript
74// MUST load font before any text operations
75await figma.loadFontAsync({ family: "Inter", style: "Regular" });
76 
77const text = figma.createText();
78text.fontName = { family: "Inter", style: "Regular" };
79text.fontSize = 16;
80text.lineHeight = { value: 24, unit: "PIXELS" };
81text.letterSpacing = { value: 0, unit: "PERCENT" };
82text.characters = "Hello World";
83text.fills = [{ type: "SOLID", color: { r: 0.1, g: 0.1, b: 0.12 } }];
84```
85 
86### Rectangles
87 
88```javascript
89const rect = figma.createRectangle();
90rect.name = "Background";
91rect.resize(400, 300);
92rect.cornerRadius = 12;
93rect.fills = [{ type: "SOLID", color: { r: 0.95, g: 0.95, b: 0.96 } }];
94```
95 
96### Ellipses
97 
98```javascript
99const circle = figma.createEllipse();
100circle.name = "Avatar Circle";
101circle.resize(48, 48);
102circle.fills = [{ type: "SOLID", color: { r: 0.85, g: 0.87, b: 0.90 } }];
103```
104 
105### Lines
106 
107```javascript
108const line = figma.createLine();
109line.name = "Divider";
110line.resize(400, 0);
111line.strokes = [{ type: "SOLID", color: { r: 0, g: 0, b: 0 }, opacity: 0.08 }];
112line.strokeWeight = 1;
113```
114 
115### SVG Import
116 
117```javascript
118const svgString = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
119  <path d="M5 12h14M12 5l7 7-7 7" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
120</svg>`;
121 
122const node = figma.createNodeFromSvg(svgString);
123node.name = "Icon/Arrow Right";
124node.resize(24, 24);
125```
126 
127## Fills & Strokes
128 
129### Solid Fill
130 
131```javascript
132node.fills = [{ type: "SOLID", color: { r: 0.2, g: 0.2, b: 0.25 } }];
133```
134 
135### Fill with Opacity
136 
137```javascript
138node.fills = [{ type: "SOLID", color: { r: 0.2, g: 0.2, b: 0.25 }, opacity: 0.5 }];
139```
140 
141### No Fill (Transparent)
142 
143```javascript
144node.fills = [];
145```
146 
147### Linear Gradient
148 
149```javascript
150node.fills = [{
151  type: "GRADIENT_LINEAR",
152  gradientStops: [
153    { color: { r: 0.2, g: 0.36, b: 0.96, a: 1 }, position: 0 },
154    { color: { r: 0.56, g: 0.24, b: 0.88, a: 1 }, position: 1 }
155  ],
156  gradientTransform: [[1, 0, 0], [0, 1, 0]]
157}];
158```
159 
160### Strokes
161 
162```javascript
163node.strokes = [{ type: "SOLID", color: { r: 0.85, g: 0.85, b: 0.87 } }];
164node.strokeWeight = 1;
165node.strokeAlign = "INSIDE";  // "CENTER", "OUTSIDE"
166```
167 
168### Multiple Fills (Layered)
169 
170```javascript
171node.fills = [
172  { type: "SOLID", color: { r: 0.95, g: 0.95, b: 0.96 } },
173  { type: "SOLID", color: { r: 0.2, g: 0.36, b: 0.96 }, opacity: 0.05 }
174];
175```
176 
177## Auto Layout
178 
179### Setting Up Auto Layout
180 
181```javascript
182const frame = figma.createFrame();
183frame.layoutMode = "VERTICAL";              // or "HORIZONTAL"
184frame.primaryAxisSizingMode = "AUTO";       // Hug main axis
185frame.counterAxisSizingMode = "FIXED";      // Fixed cross axis
186frame.resize(360, 1);                        // Width fixed, height auto
187frame.itemSpacing = 16;                      // Gap between children
188frame.paddingTop = 24;
189frame.paddingBottom = 24;
190frame.paddingLeft = 24;
191frame.paddingRight = 24;
192```
193 
194### Alignment
195 
196```javascript
197// Main axis (direction of layout)
198frame.primaryAxisAlignItems = "MIN";            // Start
199frame.primaryAxisAlignItems = "CENTER";         // Center
200frame.primaryAxisAlignItems = "MAX";            // End
201frame.primaryAxisAlignItems = "SPACE_BETWEEN";  // Distribute
202 
203// Cross axis
204frame.counterAxisAlignItems = "MIN";     // Start
205frame.counterAxisAlignItems = "CENTER";  // Center
206frame.counterAxisAlignItems = "MAX";     // End
207// NOTE: 'STRETCH' is NOT valid — use 'MIN' + child.layoutSizingX = 'FILL'
208```
209 
210### Child Sizing
211 
212```javascript
213// IMPORTANT: FILL can only be set AFTER the child is appended to an auto-layout parent
214parent.appendChild(child)
215child.layoutSizingHorizontal = "FILL";   // Stretch to parent
216child.layoutSizingHorizontal = "HUG";    // Shrink to content
217child.layoutSizingHorizontal = "FIXED";  // Manual width
218 
219child.layoutSizingVertical = "FILL";
220child.layoutSizingVertical = "HUG";
221child.layoutSizingVertical = "FIXED";
222```
223 
224### Wrapping (Grid-like Layout)
225 
226```javascript
227frame.layoutMode = "HORIZONTAL";
228frame.layoutWrap = "WRAP";
229frame.itemSpacing = 24;          // Horizontal gap
230frame.counterAxisSpacing = 24;   // Vertical gap (between rows)
231```
232 
233### Absolute Positioning Within Auto Layout
234 
235```javascript
236child.layoutPositioning = "ABSOLUTE";
237child.constraints = { horizontal: "MAX", vertical: "MIN" };  // Top-right
238child.x = parentWidth - childWidth - 8;
239child.y = 8;
240```
241 
242## Effects
243 
244### Drop Shadow
245 
246```javascript
247node.effects = [{
248  type: "DROP_SHADOW",
249  color: { r: 0, g: 0, b: 0, a: 0.08 },
250  offset: { x: 0, y: 4 },
251  radius: 16,
252  spread: -2,
253  visible: true,
254  blendMode: "NORMAL"
255}];
256```
257 
258### Inner Shadow
259 
260```javascript
261node.effects = [{
262  type: "INNER_SHADOW",
263  color: { r: 0, g: 0, b: 0, a: 0.05 },
264  offset: { x: 0, y: 1 },
265  radius: 2,
266  spread: 0,
267  visible: true,
268  blendMode: "NORMAL"
269}];
270```
271 
272### Background Blur
273 
274```javascript
275node.effects = [{
276  type: "BACKGROUND_BLUR",
277  radius: 16,
278  visible: true
279}];
280```
281 
282### Layer Blur
283 
284```javascript
285node.effects = [{
286  type: "LAYER_BLUR",
287  radius: 8,
288  visible: true
289}];
290```
291 
292### Multiple Effects
293 
294```javascript
295node.effects = [
296  { type: "DROP_SHADOW", color: { r: 0, g: 0, b: 0, a: 0.04 }, offset: { x: 0, y: 1 }, radius: 3, spread: 0, visible: true, blendMode: "NORMAL" },
297  { type: "DROP_SHADOW", color: { r: 0, g: 0, b: 0, a: 0.06 }, offset: { x: 0, y: 8 }, radius: 24, spread: -4, visible: true, blendMode: "NORMAL" }
298];
299```
300 
301## Opacity & Blend Modes
302 
303```javascript
304node.opacity = 0.5;
305node.blendMode = "NORMAL";    // "MULTIPLY", "SCREEN", "OVERLAY", "DARKEN", "LIGHTEN", etc.
306```
307 
308## Corner Radius
309 
310```javascript
311// Uniform
312node.cornerRadius = 12;
313 
314// Per-corner
315node.topLeftRadius = 12;
316node.topRightRadius = 12;
317node.bottomLeftRadius = 0;
318node.bottomRightRadius = 0;
319```
320 
321## Clipping
322 
323```javascript
324frame.clipsContent = true;   // Children clipped to frame bounds
325```
326 
327## Grouping & Organization
328 
329### Groups
330 
331```javascript
332const group = figma.group([node1, node2, node3], figma.currentPage);
333group.name = "Grouped Elements";
334```
335 
336### Sections
337 
338```javascript
339const section = figma.createSection();
340section.name = "My Section";
341section.resizeWithoutConstraints(800, 600);
342section.x = 0;
343section.y = 0;
344// IMPORTANT: Sections don't auto-resize — always resize after adding content
345```
346 
347### Appending Children
348 
349```javascript
350parentFrame.appendChild(childNode);
351 
352// Insert at a specific index
353parentFrame.insertChild(0, childNode);  // Insert at beginning
354```
355 
356## Components & Variants
357 
358### Create Component
359 
360```javascript
361const component = figma.createComponent();
362component.name = "Button/Primary";
363component.description = "Primary action button.";
364```
365 
366### Create Instance
367 
368```javascript
369const instance = component.createInstance();
370instance.x = 200;
371instance.y = 100;
372```
373 
374### Import Components by Key (Team Libraries)
375 
376These methods import components from **team libraries** (not the same file). For components in the current file, use `figma.getNodeByIdAsync()` or `findOne()`/`findAll()`.
377 
378```javascript
379// Import a published component from a team library by its key
380const comp = await figma.importComponentByKeyAsync(componentKey)
381const instance = comp.createInstance()
382 
383// Import a published component set from a team library by its key
384const set = await figma.importComponentSetByKeyAsync(componentSetKey)
385const variant = set.defaultVariant
386const variantInstance = variant.createInstance()
387```
388 
389### Combine as Variants
390 
391```javascript
392// IMPORTANT: Pass ComponentNodes (not frames)
393const componentSet = figma.combineAsVariants(
394  [variantA, variantB, variantC],
395  figma.currentPage
396);
397componentSet.name = "Button";
398componentSet.description = "Button component with multiple variants.";
399 
400// CRITICAL: Layout variants in a grid after combining (they stack at 0,0)
401let maxX = 0, maxY = 0;
402componentSet.children.forEach((child, i) => {
403  child.x = (i % numCols) * colWidth;
404  child.y = Math.floor(i / numCols) * rowHeight;
405});
406for (const child of componentSet.children) {
407  maxX = Math.max(maxX, child.x + child.width);
408  maxY = Math.max(maxY, child.y + child.height);
409}
410componentSet.resizeWithoutConstraints(maxX + 40, maxY + 40);
411```
412 
413### Component Properties
414 
415```javascript
416// addComponentProperty returns a STRING key — capture it!
417const labelKey = component.addComponentProperty("label", "TEXT", "Button");
418const showIconKey = component.addComponentProperty("showIcon", "BOOLEAN", true);
419const iconSlotKey = component.addComponentProperty("iconSlot", "INSTANCE_SWAP", defaultIconId);
420 
421// MUST link properties to child nodes via componentPropertyReferences
422labelNode.componentPropertyReferences = { characters: labelKey };
423iconInstance.componentPropertyReferences = {
424  visible: showIconKey,
425  mainComponent: iconSlotKey
426};
427```
428 
429## Styles
430 
431### Text Style
432 
433```javascript
434await figma.loadFontAsync({ family: "Inter", style: "Regular" });
435 
436const style = figma.createTextStyle();
437style.name = "Body/Default";
438style.fontName = { family: "Inter", style: "Regular" };
439style.fontSize = 16;
440style.lineHeight = { value: 24, unit: "PIXELS" };
441style.letterSpacing = { value: 0, unit: "PERCENT" };
442 
443// Apply to a text node
444textNode.textStyleId = style.id;
445```
446 
447### Effect Style
448 
449```javascript
450const shadowStyle = figma.createEffectStyle();
451shadowStyle.name = "Shadow/Subtle";
452shadowStyle.effects = [{
453  type: "DROP_SHADOW",
454  color: { r: 0, g: 0, b: 0, a: 0.06 },
455  offset: { x: 0, y: 2 },
456  radius: 8,
457  spread: 0,
458  visible: true,
459  blendMode: "NORMAL"
460}];
461 
462// Apply to a node
463frame.effectStyleId = shadowStyle.id;
464```
465 
466## Cloning & Duplication
467 
468```javascript
469const clone = originalNode.clone();
470clone.x = originalNode.x + originalNode.width + 40;
471clone.name = "Copy of " + originalNode.name;
472```
473 
474## Finding Nodes
475 
476```javascript
477// Find by name on current page
478const node = figma.currentPage.findOne(n => n.name === "My Frame");
479 
480// Find all by type
481const allTexts = figma.currentPage.findAll(n => n.type === "TEXT");
482 
483// Find all by name pattern
484const allButtons = figma.currentPage.findAll(n => n.name.startsWith("Button/"));
485```
486 
487## Layout Grids
488 
489```javascript
490frame.layoutGrids = [
491  {
492    pattern: "COLUMNS",
493    alignment: "STRETCH",
494    count: 12,
495    gutterSize: 24,
496    offset: 80,
497    visible: true
498  }
499];
500```
501 
502## Constraints (Non-Auto-Layout Frames)
503 
504```javascript
505child.constraints = {
506  horizontal: "LEFT_RIGHT",  // LEFT, RIGHT, CENTER, LEFT_RIGHT, SCALE
507  vertical: "TOP"            // TOP, BOTTOM, CENTER, TOP_BOTTOM, SCALE
508};
509```
510 
511## Viewport & Zoom
512 
513```javascript
514// Zoom to fit specific nodes
515figma.viewport.scrollAndZoomIntoView([frame1, frame2]);
516```
517