1# Variable & Token API Patterns
2 
3> Part of the [use_figma skill](../SKILL.md). How to correctly create, bind, scope, and alias variables using the Plugin API.
4>
5> For design system context (aliasing strategy, mode decisions, code syntax philosophy, grouping conventions), see [wwds-variables](working-with-design-systems/wwds-variables.md).
6 
7## Contents
8 
9- Creating Variable Collections and Modes
10- Creating Variables (All Types)
11- Binding Variables to Node Properties
12- Variable Scopes: What They Are and How to Set Them
13- Variable Aliasing (VARIABLE_ALIAS)
14- Code Syntax (setVariableCodeSyntax)
15- Importing Library Variables
16- Discovering Existing Variables in the File
17- Effect Styles (For Shadows)
18 
19 
20## Creating Variable Collections and Modes
21 
22```javascript
23const collection = figma.variables.createVariableCollection("MyCollection");
24 
25// A new collection starts with 1 mode named "Mode 1" — always rename it
26collection.renameMode(collection.modes[0].modeId, "Light");
27 
28// Add additional modes (returns the new modeId)
29const darkModeId = collection.addMode("Dark");
30const lightModeId = collection.modes[0].modeId;
31```
32 
33**Mode limits are plan-dependent:** Free = 1 mode, Professional = up to 4, Organization/Enterprise = 40+. If you need many modes, split across multiple collections.
34 
35## Creating Variables (All Types)
36 
37`figma.variables.createVariable(name, collection, resolvedType)` — the second argument accepts a collection object or ID string (object preferred).
38 
39```javascript
40// COLOR — values use {r, g, b, a} (all 0–1 range, includes alpha)
41const colorVar = figma.variables.createVariable("my-color", collection, "COLOR");
42colorVar.setValueForMode(modeId, { r: 0.2, g: 0.36, b: 0.96, a: 1 });
43 
44// FLOAT — for spacing, radii, sizing, numeric values
45const floatVar = figma.variables.createVariable("my-spacing", collection, "FLOAT");
46floatVar.setValueForMode(modeId, 16);
47 
48// STRING — for font families, font style names, any text value
49const stringVar = figma.variables.createVariable("my-font", collection, "STRING");
50stringVar.setValueForMode(modeId, "Inter");
51 
52// BOOLEAN
53const boolVar = figma.variables.createVariable("my-flag", collection, "BOOLEAN");
54boolVar.setValueForMode(modeId, true);
55```
56 
57**Note:** Paint colors use `{r, g, b}` (no alpha), but COLOR variable values use `{r, g, b, a}` (with alpha). Don't mix them up.
58 
59## Binding Variables to Node Properties
60 
61### Color Bindings (Fills, Strokes)
62 
63`setBoundVariableForPaint` returns a **NEW paint** — you must capture the return value:
64 
65```javascript
66// Create a base paint, bind the variable, assign the result
67const basePaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } };
68const boundPaint = figma.variables.setBoundVariableForPaint(basePaint, "color", colorVar);
69node.fills = [boundPaint];
70 
71// Only SOLID paints support color variable binding — gradients/images will throw
72```
73 
74### Numeric Bindings (Spacing, Radii, Sizing)
75 
76`setBoundVariable` binds FLOAT/STRING/BOOLEAN variables to node properties:
77 
78```javascript
79// Padding
80node.setBoundVariable("paddingTop", spacingVar);
81node.setBoundVariable("paddingBottom", spacingVar);
82node.setBoundVariable("paddingLeft", spacingVar);
83node.setBoundVariable("paddingRight", spacingVar);
84 
85// Gap
86node.setBoundVariable("itemSpacing", gapVar);
87node.setBoundVariable("counterAxisSpacing", gapVar);
88 
89// Corner radius — use individual corners, NOT cornerRadius
90node.setBoundVariable("topLeftRadius", radiusVar);
91node.setBoundVariable("topRightRadius", radiusVar);
92node.setBoundVariable("bottomLeftRadius", radiusVar);
93node.setBoundVariable("bottomRightRadius", radiusVar);
94 
95// Size
96node.setBoundVariable("width", sizeVar);
97node.setBoundVariable("height", sizeVar);
98node.setBoundVariable("minWidth", sizeVar);
99node.setBoundVariable("maxWidth", sizeVar);
100 
101// Other
102node.setBoundVariable("opacity", opacityVar);
103node.setBoundVariable("strokeWeight", strokeVar);
104```
105 
106**Not bindable via setBoundVariable:** `fontSize`, `fontWeight`, `lineHeight` — set these directly on text nodes.
107 
108### Effect Bindings
109 
110```javascript
111const effectCopy = JSON.parse(JSON.stringify(node.effects[0]));
112const newEffect = figma.variables.setBoundVariableForEffect(effectCopy, "color", colorVar);
113// ⚠️ Returns a NEW effect — must capture return value!
114node.effects = [newEffect];
115// Valid fields: "color" (COLOR), "radius" | "spread" | "offsetX" | "offsetY" (FLOAT)
116```
117 
118### Applying a Mode to a Frame
119 
120```javascript
121// All bound children of this frame will resolve to the specified mode's values
122frame.setExplicitVariableModeForCollection(collection, modeId);
123```
124 
125Without this, all nodes use the collection's default (first) mode.
126 
127## Variable Scopes: What They Are and How to Set Them
128 
129`variable.scopes` controls which Figma property pickers show the variable. The default is `["ALL_SCOPES"]` which shows it everywhere — this is almost never what you want.
130 
131```javascript
132variable.scopes = ["FRAME_FILL", "SHAPE_FILL"];  // only fill pickers
133variable.scopes = ["TEXT_FILL"];                   // only text color picker
134variable.scopes = ["GAP"];                         // only gap/spacing pickers
135variable.scopes = ["CORNER_RADIUS"];               // only radius pickers
136variable.scopes = [];                              // hidden from all pickers
137```
138 
139**All valid scope values:**
140`ALL_SCOPES`, `TEXT_CONTENT`, `CORNER_RADIUS`, `WIDTH_HEIGHT`, `GAP`, `ALL_FILLS`, `FRAME_FILL`, `SHAPE_FILL`, `TEXT_FILL`, `STROKE_COLOR`, `STROKE_FLOAT`, `EFFECT_FLOAT`, `EFFECT_COLOR`, `OPACITY`, `FONT_FAMILY`, `FONT_STYLE`, `FONT_WEIGHT`, `FONT_SIZE`, `LINE_HEIGHT`, `LETTER_SPACING`, `PARAGRAPH_SPACING`, `PARAGRAPH_INDENT`
141 
142**Always set scopes explicitly** — `ALL_SCOPES` is the default but almost never what you want. For a comprehensive scope-to-use-case mapping table, see [token-creation.md § Variable Scopes — Complete Reference Table](../../figma-generate-library/references/token-creation.md).
143 
144**Always check the existing file's scope patterns before creating variables** — match whatever convention is already in use. See "Discovering Existing Variables" below.
145 
146## Variable Aliasing (VARIABLE_ALIAS)
147 
148A variable's value can reference another variable via alias. This is how semantic tokens reference primitive tokens:
149 
150```javascript
151// Set a variable's value as an alias to another variable
152semanticVar.setValueForMode(modeId, {
153  type: 'VARIABLE_ALIAS',
154  id: primitiveVar.id
155});
156```
157 
158When the primitive changes, the semantic variable updates automatically across all modes.
159 
160## Code Syntax (setVariableCodeSyntax)
161 
162Links a Figma variable back to its code counterpart. Call once per platform:
163 
164```javascript
165variable.setVariableCodeSyntax('WEB', 'var(--color-bg-default)');
166variable.setVariableCodeSyntax('ANDROID', 'colorBgDefault');
167variable.setVariableCodeSyntax('iOS', 'Color.bgDefault');
168 
169// Read back: variable.codeSyntax → { WEB: '...', ANDROID: '...', iOS: '...' }
170```
171 
172**When deriving CSS names from Figma names**, replace both slashes AND spaces with hyphens:
173 
174```javascript
175// WRONG — leaves spaces in CSS variable name
176`var(--${figmaName.replace(/\//g, '-').toLowerCase()})`
177 
178// CORRECT — replace all whitespace and slashes
179`var(--${figmaName.replace(/[\s\/]+/g, '-').toLowerCase()})`
180 
181// BEST — use the original CSS variable name from the source, not a derived one
182`var(${token.cssVar})`
183```
184 
185## Importing Library Variables
186 
187For variables from **team libraries** (not the current file), use `importVariableByKeyAsync`:
188 
189```javascript
190// Import a single variable by its key
191const colorVar = await figma.variables.importVariableByKeyAsync("VARIABLE_KEY");
192// Now use it like any local variable
193const paint = figma.variables.setBoundVariableForPaint(
194  { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', colorVar
195);
196node.fills = [paint];
197```
198 
199To discover available library variable collections and their variables:
200 
201```javascript
202// List all available library variable collections
203const libCollections = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
204// Each has: name, key, libraryName
205 
206// Get variables in a specific library collection
207const libVars = await figma.teamLibrary.getVariablesInLibraryCollectionAsync(libCollections[0].key);
208// Each has: name, key, resolvedType
209// Import the ones you need:
210const imported = await figma.variables.importVariableByKeyAsync(libVars[0].key);
211```
212 
213**When to import vs. use local:** If `variable.remote === true`, it's from a library — you can reference it directly if already imported, or import by key. If `remote === false`, it's local to the file — use `getVariableByIdAsync` directly.
214 
215## Discovering Existing Variables in the File
216 
217**Always inspect the file's existing variables before creating new ones.** Different files use different naming conventions, scope patterns, and collection structures. Match what's already there.
218 
219### List collections with mode info
220 
221```javascript
222const collections = await figma.variables.getLocalVariableCollectionsAsync();
223const results = collections.map(c => ({
224  name: c.name,
225  id: c.id,
226  varCount: c.variableIds.length,
227  modes: c.modes.map(m => ({ name: m.name, id: m.modeId }))
228}));
229return results;
230```
231 
232### Inspect scope patterns used in existing variables
233 
234```javascript
235const collections = await figma.variables.getLocalVariableCollectionsAsync();
236const scopeGroups = {};
237for (const c of collections) {
238  for (const id of c.variableIds) {
239    const v = await figma.variables.getVariableByIdAsync(id);
240    const key = JSON.stringify(v.scopes);
241    if (!scopeGroups[key]) scopeGroups[key] = [];
242    scopeGroups[key].push(v.name);
243  }
244}
245return scopeGroups;
246```
247 
248### Build a name→variable lookup for reuse
249 
250```javascript
251const varByName = {};
252for (const v of await figma.variables.getLocalVariablesAsync()) {
253  varByName[v.name] = v;
254}
255 
256// Bind to existing variable by name — no hex values needed
257function bindFill(node, varName) {
258  const v = varByName[varName];
259  if (!v) throw new Error(`Variable not found: ${varName}`);
260  const paint = figma.variables.setBoundVariableForPaint(
261    { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', v
262  );
263  node.fills = [paint];
264}
265```
266 
267**Only create new variables for tokens that have no match in the file.** After building the lookup, compare against the needed tokens and create variables only for the delta.
268 
269## Listing Collections with Full Variable Details
270 
271The async API returns richer data including code syntax and scopes per variable:
272 
273```javascript
274/**
275 * Lists all local variable collections defined in the current Figma file,
276 * including metadata for their modes and variables.
277 *
278 * @returns {Promise<Array<{
279 *   name: string,
280 *   id: string,
281 *   modes: Array<[name: string, modeId: string]>,
282 *   variables: Array<[name: string, id: string, codeSyntax: object, scopes: string[]]>
283 * }>>}
284 */
285async function listVariableCollectionsAndVariables() {
286  const collections = await figma.variables.getLocalVariableCollectionsAsync();
287  const results = [];
288  for (const collection of collections) {
289    const vars = [];
290    for (const id of collection.variableIds) {
291      const v = await figma.variables.getVariableByIdAsync(id);
292      vars.push([v.name, v.id, v.codeSyntax, v.scopes]);
293    }
294    results.push({
295      name: collection.name,
296      id: collection.id,
297      modes: collection.modes.map(m => [m.name, m.modeId]),
298      variables: vars
299    });
300  }
301  return results;
302}
303```
304 
305Full runnable script:
306 
307```javascript
308const results = await listVariableCollectionsAndVariables();
309return results;
310```
311 
312## Setting and Removing Code Syntax
313 
314Must be executed in the file the variable is defined in:
315 
316```javascript
317/**
318 * Set the code syntax for a variable for a specific platform.
319 *
320 * @param {string} variableId
321 * @param {'WEB'|'ANDROID'|'iOS'} platform
322 * @param {string} syntax
323 */
324async function setVariableCodeSyntax(variableId, platform, syntax) {
325  const variable = await figma.variables.getVariableByIdAsync(variableId);
326  variable.setVariableCodeSyntax(platform, syntax);
327}
328 
329/**
330 * Remove code syntax for a variable for one or more platforms.
331 *
332 * @param {string} variableId
333 * @param {Array<'WEB'|'ANDROID'|'iOS'>} platforms — defaults to all three
334 */
335async function removeVariableCodeSyntax(variableId, platforms = ["WEB", "ANDROID", "iOS"]) {
336  const variable = await figma.variables.getVariableByIdAsync(variableId);
337  for (const platform of platforms) {
338    variable.removeVariableCodeSyntax(platform);
339  }
340}
341 
342/**
343 * Set a value for a variable in a specific mode.
344 * For aliases, value must be: { type: 'VARIABLE_ALIAS', id: '<variableId>' }
345 *
346 * @param {string} variableId
347 * @param {string} modeId
348 * @param {string|number|boolean|RGB|RGBA|{type: 'VARIABLE_ALIAS', id: string}} value
349 */
350async function setVariableValueForMode(variableId, modeId, value) {
351  const variable = await figma.variables.getVariableByIdAsync(variableId);
352  variable.setValueForMode(modeId, value);
353}
354```
355 
356## Effect Styles (For Shadows)
357 
358Shadows can't be stored as variables. Use effect styles. For comprehensive patterns, see [effect-style-patterns.md](effect-style-patterns.md).
359 
360```javascript
361const shadow = figma.createEffectStyle();
362shadow.name = "Shadow/Subtle";
363shadow.effects = [{
364  type: "DROP_SHADOW",
365  color: { r: 0, g: 0, b: 0, a: 0.06 },
366  offset: { x: 0, y: 2 },
367  radius: 8,
368  spread: 0,
369  visible: true,
370  blendMode: "NORMAL"
371}];
372 
373// Apply to a node
374frame.effectStyleId = shadow.id;
375```
376