figma-variables

Figma Variables API

Variables (design tokens) enable dynamic theming, responsive design, and design system management.

Core Concepts

• Variable: A named value that can change based on mode (e.g., light/dark theme)
• Collection: A group of related variables (e.g., "Colors", "Spacing")
• Mode: A variant of values within a collection (e.g., "Light", "Dark")

Getting Variables

// Get all local variable collections
const collections = await figma.variables.getLocalVariableCollectionsAsync()

// Get a specific variable by ID
const variable = await figma.variables.getVariableByIdAsync(variableId)

// Get variables from a collection
for (const collection of collections) {
  for (const variableId of collection.variableIds) {
    const variable = await figma.variables.getVariableByIdAsync(variableId)
    console.log(variable?.name, variable?.resolvedType)
  }
}

Creating Variables

// Create a new collection (sync)
const collection = figma.variables.createVariableCollection('My Tokens')

// Create variables of different types (pass VariableCollection object, not ID)
const colorVar = figma.variables.createVariable('primary', collection, 'COLOR')
const numberVar = figma.variables.createVariable(
  'spacing-md',
  collection,
  'FLOAT',
)
const stringVar = figma.variables.createVariable(
  'font-family',
  collection,
  'STRING',
)
const boolVar = figma.variables.createVariable(
  'is-enabled',
  collection,
  'BOOLEAN',
)

// Set values for the default mode
colorVar.setValueForMode(collection.defaultModeId, { r: 0.2, g: 0.4, b: 1 })
numberVar.setValueForMode(collection.defaultModeId, 16)

Working with Modes

// Add a new mode to a collection (sync)
const darkModeId = collection.addMode('Dark')

// Set values for different modes
colorVar.setValueForMode(collection.defaultModeId, { r: 1, g: 1, b: 1 }) // Light
colorVar.setValueForMode(darkModeId, { r: 0.1, g: 0.1, b: 0.1 }) // Dark

// Get value for a specific mode
const lightValue = colorVar.valuesByMode[collection.defaultModeId]
const darkValue = colorVar.valuesByMode[darkModeId]