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: {type: "VARIABLE_ALIAS", name: "other/variable"}.
// 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

5 methods available.

list

read

Search variables within a collection

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[]
↳ 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
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.

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
↳ name	string	Name of the created variable

update

edit

Update variable metadata and/or set values

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