Core concepts

Five ideas explain everything else in this documentation.

---

Token

A named, typed value. A token has:

Part	Example	Notes
Name	primary.500	A dot path. Allowed characters: a–z A–Z 0–9 . - _. No .., no leading or trailing .
Type	color	One of the supported types. Determines the value format and the validation
Value	{ colorSpace: "srgb", components: [...] }	A structured DTCG object, not a string
Token set	global/color	Which set the token lives in
Description	optional	Free text, exported as $description

Names must be unique. Renaming a token updates every reference pointing at it, and the dialog tells you how many were rewritten.

---

Token set

A slash-separated path that groups tokens: global/color, brand/acme/color, mode/dark.

Sets are the unit that themes switch on and that folder export writes as files. A set with the path brand/acme/color exports to brand/acme/color.json.

Sets are pure organisation — a token in global/color and one in brand/acme/color can have the same name, because their full paths differ.

→ Token sets guide

---

Theme

A named combination of token sets, each switched to one of three states:

State	Meaning
Enabled	The set’s tokens are visible — they export, sync, and show in the panel
Reference	The set is available for references to resolve against, but its tokens are not themselves output
Disabled	The set is ignored entirely

Themes belong to groups (brand, mode, density, …). Only one theme per group can be active at a time — activating Dark automatically deactivates Light in the same group. Activating a theme in a different group is independent, so brand: Acme × mode: Dark is a valid combination.

→ Themes guide

---

Reference (alias)

A token can point at another token instead of holding a literal value:

{ "$type": "color", "$value": "{global.color.primary.500}" }

The syntax is {path.to.token} — one reference per value, resolved against the currently enabled and reference-state sets.

References work at two levels:

• Whole token — the entire value is a reference
• Slot — one field of a composite value is a reference, e.g. only the color field of a border token

If a reference cannot be resolved, the token tile shows a broken-link icon and “Reference cannot be resolved” rather than silently applying nothing.

→ References & aliases

---

Binding

When you apply a token to a layer, the plugin writes a binding onto that layer recording which token was applied and to which property.

Bindings power two things:

• The Inspect tab, which lists every binding on the current selection and lets you remove them
• Sync to selection, which re-applies every stored binding — so after editing primary.500, you re-push the new value onto every bound layer

A binding is a record, not a live link. Changing a token does not automatically update layers; you re-apply or run Sync to selection.

→ Inspecting bindings

---

How they fit together

Token set  global/color
└── Token  primary.500        $type: color   $value: #3b82f6
                  ▲
                  │ {global.color.primary.500}      ← reference
Token set  comp/button
└── Token  bg.default         $type: color   $value: {global.color.primary.500}
                  │
                  │ apply → fills
                  ▼
Figma layer  "Button/Primary"  ← binding recorded on the layer

A theme decides which of those sets are switched on when the document is resolved, exported, or synced.