Variable Collections

管理变量集合——设计令牌的文档级 API。

Type reference

// Variable collections group design tokens and define their modes (e.g. Light/Dark, Desktop/Mobile).
// All ID params accept both IDs and display names.
// ---
// valuesByMode: values keyed by mode name, e.g. {"Light": "#FFF", "Dark": "#111"}.
// Aliases in variable values use {type: "VARIABLE_ALIAS", name: "other/variable"}.
// Paint[] VariableAlias uses {type:"VARIABLE_ALIAS", id:"<VariableID>"}; variable_collections.get includes each variable id. Prefer *VariableName helpers when available.
// scopes: see variables endpoint for full list.
// Deleting a collection deletes all variables inside it.
// The default mode cannot be removed. Use add_mode/remove_mode for additional modes.
// 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.

8 methods available.

list

read

List variable collections

Parameter	Type	Required	Description
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
↳ name	string
↳ modes	string[]	Mode names
↳ variableCount	number	Number of variables

get

read

Get collection with all variables and values (full document)

Parameter	Type	Required	Description
id	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
name	string
modes	string[]	Mode names (e.g. ['Light', 'Dark'])
variables	object[]	All variables in this collection
↳ 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

create

create

Create a collection with modes and variables in one call

Example

variable_collections(method:"create", items:[{name:"Tokens", variables:[{name:"bg/canvas", type:"COLOR", value:"#F7F8FA", scopes:["ALL_FILLS"]}, {name:"bg/surface", type:"COLOR", value:"#FFFFFF", scopes:["ALL_FILLS"]}, {name:"bg/accent", type:"COLOR", value:"#2563EB", scopes:["ALL_FILLS"]}, {name:"bg/muted", type:"COLOR", value:"#E5E7EB", scopes:["ALL_FILLS"]}, {name:"text/primary", type:"COLOR", value:"#111827", scopes:["TEXT_FILL"]}, {name:"text/secondary", type:"COLOR", value:"#4B5563", scopes:["TEXT_FILL"]}, {name:"text/inverse", type:"COLOR", value:"#FFFFFF", scopes:["TEXT_FILL"]}, {name:"border/subtle", type:"COLOR", value:"#D1D5DB", scopes:["STROKE_COLOR"]}, {name:"icon/primary", type:"COLOR", value:{type:"VARIABLE_ALIAS", name:"text/primary"}, scopes:["ALL_FILLS","STROKE_COLOR"]}, {name:"status/success", type:"COLOR", value:"#16A34A", scopes:["ALL_FILLS"]}, {name:"space/8", type:"FLOAT", value:8, scopes:["GAP"]}, {name:"space/12", type:"FLOAT", value:12, scopes:["GAP"]}, {name:"space/16", type:"FLOAT", value:16, scopes:["GAP"]}, {name:"space/24", type:"FLOAT", value:24, scopes:["GAP"]}, {name:"radius/8", type:"FLOAT", value:8, scopes:["CORNER_RADIUS"]}, {name:"radius/12", type:"FLOAT", value:12, scopes:["CORNER_RADIUS"]}, {name:"radius/16", type:"FLOAT", value:16, scopes:["CORNER_RADIUS"]}, {name:"stroke/1", type:"FLOAT", value:1, scopes:["STROKE_FLOAT"]}]}])

Parameter	Type	Required	Description
items	object[]	✓	Array of collection documents
↳ name	string	✓	Collection name
↳ modes	string[]	✗	Mode names (e.g. ['Light', 'Dark']). Omit for single-mode collection.
↳ variables	object[]	✗	Variables to create inside this collection
↳ name	string	✓	Variable name (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"})
↳ description	string	✗
↳ scopes	string[]	✗	Restrict where variable can be applied (default: ALL_SCOPES)

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string

update

edit

Rename collections

Parameter	Type	Required	Description
items	object[]	✓	Array of {id, name}
↳ id	string	✓	Collection ID or name
↳ name	string	✓	New name

Response

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

delete

edit

Delete collections

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

Response

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

add_mode

create

Add a mode to a collection

Parameter	Type	Required	Description
items	object[]	✓	Array of {collectionId, name}
↳ collectionId	string	✓	Collection ID or name
↳ name	string	✓	Mode name

Response

Field	Type	Description
results	object[]	One entry per input item
↳ modeId	string

rename_mode

edit

Rename a mode

Parameter	Type	Required	Description
items	object[]	✓	Array of {collectionId, modeId, name}
↳ collectionId	string	✓	Collection ID or name
↳ modeId	string	✓	Mode ID or name (e.g. "Dark")
↳ name	string	✓	New name

Response

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

remove_mode

edit

Remove a mode from a collection

Parameter	Type	Required	Description
items	object[]	✓	Array of {collectionId, modeId}
↳ collectionId	string	✓	Collection ID or name
↳ modeId	string	✓	Mode ID or name (e.g. "Dark")

Response

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