References and aliases

Reference2026-07-27

A reference lets a token point at another token instead of repeating its value. This is what turns a flat list of values into a system.

Syntax

{path.to.token}

The path is the token’s full path: its set path with / replaced by ., plus its name. A token named primary.500 in the set global/color is referenced as {global.color.primary.500}.

Rules:

Exactly one reference per value — you cannot concatenate
No } inside the path
Whitespace around the braces is not part of the path

Two levels of reference

Whole token

The entire value is an alias:

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

Slot

One field of a composite value is an alias, the rest are literals:

{
  "$type": "border",
  "$value": {
    "color": "{semantic.color.border.subtle}",
    "width": { "value": 1, "unit": "px" },
    "style": "solid"
  }
}

Every slot of every composite type accepts this. In the token dialog, the link icon on a field toggles it between literal and reference mode.

Which types can be referenced

Slot references are validated against the expected type. Twelve types are referenceable in slots:

color, dimension, fontFamily, fontWeight, duration, number, shadow, typography, border, transition, cubicBezier, strokeStyle

Not referenceable in slots: gradient, text, file, other.

Resolution

References resolve against the token sets that are Enabled or Reference under the currently active themes. A disabled set is invisible, so a reference into it breaks.

This is the mechanism behind theming: semantic.color.action can point at {brand.color.primary}, and which brand set is enabled decides what it resolves to.

Chains and cycles

References may chain — token A → B → C. Composite applicators resolve up to 10 levels deep. A cycle reports “Circular reference detected” rather than hanging.

Resolution priority

When several enabled sets define the same path, the winner is decided by set prefix — see Themes.

Broken references

A reference that does not resolve shows on the tile as a broken-link icon and red text: “Reference cannot be resolved”.

Common causes:

Cause	Fix
The target set is Disabled under the active theme	Set it to Reference or Enabled
The target token was deleted	Deleting does not rewrite references — recreate it or edit the referrer
A typo in the path	Check the full path, including the set prefix
The path uses `/` instead of `.`	Set separators become `.` in a reference

Applying a token with a broken reference reports “Invalid value … (token reference could not be resolved)”.

Renaming is safe, deleting is not

Action	References
Rename a token	Every reference to it is rewritten automatically, and the dialog reports the count
Delete a token	References are not checked or rewritten — they silently break

Search for a token’s name before deleting it.

A worked example

global/primitives/color        blue.500      = #3b82f6      ← literal
                                                   ▲
brand/acme/color               primary       = {global.primitives.color.blue.500}
                                                   ▲
semantic/color                 action.default = {brand.acme.color.primary}
                                                   ▲
comp/button                    bg.default     = {semantic.color.action.default}

Swapping brand/acme/color for brand/globex/color in the active theme re-points the whole chain. Nothing below the brand layer changes.