Variables

搜索和更新集合中的设计变量。

Type reference

// Search and update variables within a collection. collectionId is required on all methods.
// Use variable_collections to create full token sets (collection + modes + variables in one call).
// ---
// query: prefix match first, then substring. "bg/" matches bg/canvas, bg/surface, etc.
// valuesByMode: values keyed by mode name. On create, value sets all modes; on update, value sets the default mode only.
// Aliases in variable values use {type: "VARIABLE_ALIAS", name: "other/variable"}.
// Paint[] VariableAlias uses {type:"VARIABLE_ALIAS", id:"<VariableID>"}; get IDs from variables.get/list or variable_collections.get. Prefer *VariableName helpers when available.
// scopes: ALL_SCOPES, TEXT_CONTENT, WIDTH_HEIGHT, GAP, CORNER_RADIUS, 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
// Shared types:
// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2×3 matrix)
// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.

5 methods available.

list

read

Search variables within a collection

Example

variables(method:"list", collectionId:"Tokens", query:"bg/")

Parameter	Type	Required	Description
collectionId	string	✓	Collection ID or name
query	string	✗	Search query — prefix match first, then substring fallback
type	"COLOR" | "FLOAT" | "STRING" | "BOOLEAN"	✗	Filter by variable type
fields	string[]	✗	Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.
offset	number	✗	Skip N items for pagination (default 0) (default: 0)
limit	number	✗	Max items per page (default 100) (default: 100)

Response

Field	Type	Description
totalCount	number	Total matching items
returned	number	Items in this page
offset	number
limit	number
items	object[]
↳ id	string	Figma VariableID. Use as VariableAlias.id in Paint[] when needed.
↳ name	string
↳ type	string	COLOR | FLOAT | STRING | BOOLEAN
↳ valuesByMode	object	Values keyed by mode name
↳ scopes	string[]
↳ description	string

get

read

Get variable detail by name

Parameter	Type	Required	Description
name	string	✓	Variable name (unique within collection)
collectionId	string	✓	Collection ID or name
fields	string[]	✗	Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.

Response

Field	Type	Description
id	string	Figma VariableID. Use as VariableAlias.id in Paint[] when needed.
name	string
type	"COLOR" | "FLOAT" | "STRING" | "BOOLEAN"
collectionId	string	Collection display name
valuesByMode	object	Values keyed by mode name (e.g. "Light", "Dark")
description	string	Variable description
scopes	string[]	Where this variable can be applied

create

create

Create variables in a collection. Use valuesByMode for per-mode control, or value to set all modes at once.

Example

variables(method:"create", collectionId:"Tokens", items:[{name:"bg/warning", type:"COLOR", value:"#F59E0B", scopes:["ALL_FILLS"]}])

Parameter	Type	Required	Description
collectionId	string	✓	Collection ID or name
items	object[]	✓	Array of variables to create
↳ name	string	✓	Variable name (must be unique within collection)
↳ type	"COLOR" | "FLOAT" | "STRING" | "BOOLEAN"	✓	Variable type
↳ value	any	✗	Sets all modes to this value. Use valuesByMode for per-mode control.
↳ valuesByMode	object	✗	Values keyed by mode name (e.g. {"Light": "#FFF", "Dark": "#111"}). Takes precedence over value.
↳ description	string	✗	Variable description
↳ scopes	string[]	✗	Restrict where variable can be applied (default: ALL_SCOPES)

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string	Figma VariableID. Use as VariableAlias.id in Paint[] when needed.
↳ name	string	Name of the created variable

update

edit

Update variable metadata and/or set values

Example

variables(method:"update", collectionId:"Tokens", items:[{name:"bg/accent", value:"#1D4ED8"}])

Parameter	Type	Required	Description
collectionId	string	✓	Collection ID or name
items	object[]	✓	Array of variable updates
↳ name	string	✓	Variable name
↳ rename	string	✗	Rename the variable
↳ description	string	✗	Set description
↳ scopes	string[]	✗	Update scopes
↳ value	any	✗	Shorthand — sets the default mode value. Use valuesByMode for multi-mode.
↳ valuesByMode	object	✗	Values keyed by mode name. Takes precedence over value.

Response

Field	Type	Description
results	any[]	Array of "ok" or {error} per item

delete

edit

Delete variables

Parameter	Type	Required	Description
collectionId	string	✓	Collection ID or name
name	string	✗	Variable name
items	object[]	✗	Batch: [{name}, ...]
↳ name	string	✓

Response

Field	Type	Description
results	string[]	Array of "ok" per item