1# Common Patterns
2 
3> Part of the [use_figma skill](../SKILL.md). Working code examples for frequently used operations.
4 
5## Contents
6 
7- Basic Script Structure
8- Create a Styled Shape
9- Create a Text Node
10- Create Frame with Auto-Layout
11- Create Variable Collections and Bindings
12- Create Components and Import by Key
13- Component Sets with Variable Modes
14- Multi-Step Large ComponentSet Pattern
15- Read Existing Nodes and Return Data
16 
17 
18## Basic Script Structure
19 
20```js
21const createdNodeIds = []
22const mutatedNodeIds = []
23 
24// Your code here — track every node you create or mutate
25// createdNodeIds.push(newNode.id)
26// mutatedNodeIds.push(existingNode.id)
27 
28return {
29  success: true,
30  createdNodeIds,
31  mutatedNodeIds,
32  // Plus any other useful data for subsequent calls
33  count: createdNodeIds.length
34}
35```
36 
37## Create a Styled Shape
38 
39```js
40// Find clear space to the right of existing content
41const page = figma.currentPage
42let maxX = 0
43for (const child of page.children) {
44  maxX = Math.max(maxX, child.x + child.width)
45}
46 
47const rect = figma.createRectangle()
48rect.name = "Blue Box"
49rect.resize(200, 100)
50rect.fills = [{ type: 'SOLID', color: { r: 0.047, g: 0.549, b: 0.914 } }]
51rect.cornerRadius = 8
52rect.x = maxX + 100  // offset from existing content
53rect.y = 0
54figma.currentPage.appendChild(rect)
55return { nodeId: rect.id }
56```
57 
58## Create a Text Node
59 
60```js
61// Find clear space to the right of existing content
62const page = figma.currentPage
63let maxX = 0
64for (const child of page.children) {
65  maxX = Math.max(maxX, child.x + child.width)
66}
67 
68await figma.loadFontAsync({ family: "Inter", style: "Regular" })
69const text = figma.createText()
70text.characters = "Hello World"
71text.fontSize = 16
72text.fills = [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }]
73text.textAutoResize = 'WIDTH_AND_HEIGHT'
74text.x = maxX + 100
75text.y = 0
76figma.currentPage.appendChild(text)
77return { nodeId: text.id }
78```
79 
80## Create Frame with Auto-Layout
81 
82```js
83// Find clear space to the right of existing content
84const page = figma.currentPage
85let maxX = 0
86for (const child of page.children) {
87  maxX = Math.max(maxX, child.x + child.width)
88}
89 
90const frame = figma.createFrame()
91frame.name = "Card"
92frame.layoutMode = 'VERTICAL'
93frame.primaryAxisAlignItems = 'MIN'
94frame.counterAxisAlignItems = 'MIN'
95frame.paddingLeft = 16
96frame.paddingRight = 16
97frame.paddingTop = 12
98frame.paddingBottom = 12
99frame.itemSpacing = 8
100frame.layoutSizingHorizontal = 'HUG'
101frame.layoutSizingVertical = 'HUG'
102frame.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }]
103frame.cornerRadius = 8
104frame.x = maxX + 100
105frame.y = 0
106figma.currentPage.appendChild(frame)
107return { nodeId: frame.id }
108```
109 
110## Create Variable Collection with Multiple Modes
111 
112```js
113const collection = figma.variables.createVariableCollection("Theme/Colors")
114// Rename the default mode
115collection.renameMode(collection.modes[0].modeId, "Light")
116const darkModeId = collection.addMode("Dark")
117const lightModeId = collection.modes[0].modeId
118 
119const bgVar = figma.variables.createVariable("bg", collection, "COLOR")
120bgVar.setValueForMode(lightModeId, { r: 1, g: 1, b: 1, a: 1 })
121bgVar.setValueForMode(darkModeId, { r: 0.1, g: 0.1, b: 0.1, a: 1 })
122 
123const textVar = figma.variables.createVariable("text", collection, "COLOR")
124textVar.setValueForMode(lightModeId, { r: 0, g: 0, b: 0, a: 1 })
125textVar.setValueForMode(darkModeId, { r: 1, g: 1, b: 1, a: 1 })
126 
127return {
128  collectionId: collection.id,
129  lightModeId,
130  darkModeId,
131  bgVarId: bgVar.id,
132  textVarId: textVar.id
133}
134```
135 
136## Bind Color Variable to a Fill
137 
138```js
139const variable = await figma.variables.getVariableByIdAsync("VariableID:1:2")
140const rect = figma.createRectangle()
141const basePaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }
142 
143// setBoundVariableForPaint returns a NEW paint — capture it!
144const boundPaint = figma.variables.setBoundVariableForPaint(basePaint, "color", variable)
145rect.fills = [boundPaint]
146 
147return { nodeId: rect.id }
148```
149 
150## Create Component Variants with Component Properties
151 
152Component properties (TEXT, BOOLEAN, INSTANCE_SWAP) MUST be added inside the per-variant loop, BEFORE `combineAsVariants`. The component set inherits them from its children.
153 
154```js
155await figma.loadFontAsync({ family: "Inter", style: "Regular" })
156 
157// Assume defaultIconComp is an existing icon component (discovered earlier)
158const defaultIconComp = figma.getNodeById('ICON_COMPONENT_ID')
159 
160const components = []
161const variants = ["primary", "secondary"]
162 
163for (const variant of variants) {
164  const comp = figma.createComponent()
165  comp.name = `variant=${variant}`
166  comp.layoutMode = 'HORIZONTAL'
167  comp.primaryAxisAlignItems = 'CENTER'
168  comp.counterAxisAlignItems = 'CENTER'
169  comp.paddingLeft = 12
170  comp.paddingRight = 12
171  comp.paddingTop = 8
172  comp.paddingBottom = 8
173  comp.layoutSizingHorizontal = 'HUG'
174  comp.layoutSizingVertical = 'HUG'
175  comp.cornerRadius = 6
176  comp.itemSpacing = 8
177 
178  // TEXT property — label
179  const labelKey = comp.addComponentProperty('Label', 'TEXT', 'Button')
180  const label = figma.createText()
181  label.characters = "Button"
182  label.fontSize = 14
183  comp.appendChild(label)
184  label.componentPropertyReferences = { characters: labelKey }
185 
186  // BOOLEAN + INSTANCE_SWAP — icon slot
187  const showIconKey = comp.addComponentProperty('Show Icon', 'BOOLEAN', false)
188  const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', defaultIconComp.id)
189  const iconInstance = defaultIconComp.createInstance()
190  comp.insertChild(0, iconInstance)  // icon before label
191  iconInstance.componentPropertyReferences = {
192    visible: showIconKey,
193    mainComponent: iconSlotKey
194  }
195 
196  components.push(comp)
197}
198 
199const componentSet = figma.combineAsVariants(components, figma.currentPage)
200componentSet.name = "Button"
201 
202// Layout variants in a row after combining (they stack at 0,0 by default)
203const colW = 140
204componentSet.children.forEach((child, i) => {
205  child.x = i * colW
206  child.y = 0
207})
208// Resize from actual child bounds — formula-based sizing is error-prone
209let maxX = 0, maxY = 0
210for (const c of componentSet.children) {
211  maxX = Math.max(maxX, c.x + c.width)
212  maxY = Math.max(maxY, c.y + c.height)
213}
214componentSet.resizeWithoutConstraints(maxX + 40, maxY + 40)
215 
216return {
217  componentSetId: componentSet.id,
218  componentIds: components.map(c => c.id)
219}
220```
221 
222## Import a Component by Key (Team Libraries)
223 
224`importComponentByKeyAsync` and `importComponentSetByKeyAsync` import components from **team libraries** (not the same file you're working in). For components in the current file, use `figma.getNodeByIdAsync()` or `findOne()`/`findAll()` to locate them directly.
225 
226```js
227// Import a single published component by key
228const comp = await figma.importComponentByKeyAsync("COMPONENT_KEY")
229const instance = comp.createInstance()
230instance.x = 40
231instance.y = 40
232figma.currentPage.appendChild(instance)
233 
234// Import a published component set by key and select a variant
235const compSet = await figma.importComponentSetByKeyAsync("COMPONENT_SET_KEY")
236const variant =
237  compSet.children.find((c) =>
238    c.type === "COMPONENT" && c.name.includes("size=md")
239  ) || compSet.defaultVariant
240 
241const variantInstance = variant.createInstance()
242variantInstance.x = 240
243variantInstance.y = 40
244figma.currentPage.appendChild(variantInstance)
245 
246return {
247  componentId: comp.id,
248  componentSetId: compSet.id,
249  placedInstanceIds: [instance.id, variantInstance.id]
250}
251```
252 
253## Component Set with Variable Modes (Full Pattern)
254 
255```js
256await figma.loadFontAsync({ family: "Inter", style: "Medium" })
257 
258// 1. Create color collection with modes per variant
259const colors = figma.variables.createVariableCollection("Component/Colors")
260colors.renameMode(colors.modes[0].modeId, "primary")
261const primaryMode = colors.modes[0].modeId
262const secondaryMode = colors.addMode("secondary")
263 
264const bgVar = figma.variables.createVariable("bg", colors, "COLOR")
265bgVar.setValueForMode(primaryMode, { r: 0, g: 0.4, b: 0.9, a: 1 })
266bgVar.setValueForMode(secondaryMode, { r: 0, g: 0, b: 0, a: 0 })
267 
268const textVar = figma.variables.createVariable("text-color", colors, "COLOR")
269textVar.setValueForMode(primaryMode, { r: 1, g: 1, b: 1, a: 1 })
270textVar.setValueForMode(secondaryMode, { r: 0.1, g: 0.1, b: 0.1, a: 1 })
271 
272// 2. Create components with variable bindings
273const modeMap = { primary: primaryMode, secondary: secondaryMode }
274const components = []
275 
276for (const [variantName, modeId] of Object.entries(modeMap)) {
277  const comp = figma.createComponent()
278  comp.name = "variant=" + variantName
279  comp.layoutMode = "HORIZONTAL"
280  comp.primaryAxisAlignItems = "CENTER"
281  comp.counterAxisAlignItems = "CENTER"
282  comp.paddingLeft = 12; comp.paddingRight = 12
283  comp.layoutSizingHorizontal = "HUG"
284  comp.layoutSizingVertical = "HUG"
285  comp.cornerRadius = 6
286 
287  // Bind background fill to variable
288  const bgPaint = figma.variables.setBoundVariableForPaint(
289    { type: "SOLID", color: { r: 0, g: 0, b: 0 } }, "color", bgVar
290  )
291  comp.fills = [bgPaint]
292 
293  // Add text with bound color
294  const label = figma.createText()
295  label.fontName = { family: "Inter", style: "Medium" }
296  label.characters = "Button"
297  label.fontSize = 14
298  const textPaint = figma.variables.setBoundVariableForPaint(
299    { type: "SOLID", color: { r: 0, g: 0, b: 0 } }, "color", textVar
300  )
301  label.fills = [textPaint]
302  comp.appendChild(label)
303 
304  // 3. CRITICAL: Set explicit mode so this variant renders correctly
305  comp.setExplicitVariableModeForCollection(colors, modeId)
306 
307  components.push(comp)
308}
309 
310// 4. Combine into component set
311const componentSet = figma.combineAsVariants(components, figma.currentPage)
312componentSet.name = "Button"
313 
314return {
315  componentSetId: componentSet.id,
316  colorCollectionId: colors.id
317}
318```
319 
320## Large ComponentSet with Variable Modes (Multi-Step Pattern)
321 
322For component sets with many variants (50+), split into multiple `use_figma` calls:
323 
324**Call 1: Create variable collections and return IDs**
325 
326```js
327// Hex-to-0-1 helper
328const hex = (h) => {
329  if (!h) return { r: 0, g: 0, b: 0, a: 0 }; // transparent
330  return {
331    r: parseInt(h.slice(1,3), 16) / 255,
332    g: parseInt(h.slice(3,5), 16) / 255,
333    b: parseInt(h.slice(5,7), 16) / 255,
334    a: 1
335  };
336};
337 
338const coll = figma.variables.createVariableCollection("MyComponent/Colors");
339coll.renameMode(coll.modes[0].modeId, "mode1");
340const mode2Id = coll.addMode("mode2");
341 
342// Create variables from data map
343const colorData = { "bg/default": ["#0B6BCB", "#636B74"], /* ... */ };
344const modeOrder = ["mode1", "mode2"];
345const modeIds = { mode1: coll.modes[0].modeId, mode2: mode2Id };
346const varIds = {};
347 
348for (const [name, values] of Object.entries(colorData)) {
349  const v = figma.variables.createVariable(name, coll, "COLOR");
350  values.forEach((hex_val, i) => {
351    v.setValueForMode(modeIds[modeOrder[i]], hex_val ? hex(hex_val) : { r:0, g:0, b:0, a:0 });
352  });
353  varIds[name] = v.id;
354}
355 
356// Return ALL IDs — needed by subsequent calls
357return { collId: coll.id, modeIds, varIds };
358```
359 
360**Call 2: Create components using stored IDs, combine and layout**
361 
362```js
363await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
364 
365// Paste IDs from Call 1 as literals
366const collId = "VariableCollectionId:X:Y";
367const modeIds = { mode1: "X:0", mode2: "X:1" };
368const varIds = { /* ... from Call 1 ... */ };
369 
370const getVar = async (id) => await figma.variables.getVariableByIdAsync(id);
371const bindColor = async (varId) => figma.variables.setBoundVariableForPaint(
372  { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', await getVar(varId)
373);
374const collection = await figma.variables.getVariableCollectionByIdAsync(collId);
375 
376const components = [];
377for (const mode of ["mode1", "mode2"]) {
378  for (const state of ["default", "hover"]) {
379    const comp = figma.createComponent();
380    comp.name = `mode=${mode}, state=${state}`;
381    comp.layoutMode = 'HORIZONTAL';
382    comp.primaryAxisAlignItems = 'CENTER';
383    comp.counterAxisAlignItems = 'CENTER';
384    comp.layoutSizingHorizontal = 'HUG';
385    comp.layoutSizingVertical = 'HUG';
386    comp.fills = [await bindColor(varIds[`bg/${state}`])];
387    comp.setExplicitVariableModeForCollection(collection, modeIds[mode]);
388    // ... add text children ...
389    components.push(comp);
390  }
391}
392 
393// Combine — all children stack at (0,0)!
394const cs = figma.combineAsVariants(components, figma.currentPage);
395cs.name = "MyComponent";
396 
397// CRITICAL: layout variants in a structured grid mapped to variant axes.
398const stateOrder = ["default", "hover"];
399const modeOrder2 = ["mode1", "mode2"];
400const colW = 140, rowH = 56;
401 
402for (const child of cs.children) {
403  const props = Object.fromEntries(
404    child.name.split(', ').map(p => p.split('='))
405  );
406  const col = stateOrder.indexOf(props.state);
407  const row = modeOrder2.indexOf(props.mode);
408  child.x = col * colW;
409  child.y = row * rowH;
410}
411// Resize from actual child bounds
412let maxX = 0, maxY = 0;
413for (const child of cs.children) {
414  maxX = Math.max(maxX, child.x + child.width);
415  maxY = Math.max(maxY, child.y + child.height);
416}
417cs.resizeWithoutConstraints(maxX + 40, maxY + 40);
418 
419// Wrap in section
420const section = figma.createSection();
421section.name = "MyComponent Section";
422section.appendChild(cs);
423section.resizeWithoutConstraints(cs.width + 200, cs.height + 200);
424 
425return { csId: cs.id, count: components.length };
426```
427 
428## Read Existing Nodes and Return Data
429 
430```js
431const page = figma.currentPage
432const nodes = page.findAll(n => n.type === 'FRAME')
433const data = nodes.map(n => ({
434  id: n.id,
435  name: n.name,
436  width: n.width,
437  height: n.height,
438  childCount: n.children?.length || 0
439}))
440return { frames: data }
441```
442