References and aliases

A reference lets a token take its value from another token. Syntope Engine follows the DTCG specification here, so references work the same in Syntope Tokens, Syntope MCP and your files.

Syntax

{group.token}

A reference names the token path. It does not name the token set: blue.500 in the set primitives/color is {blue.500}.

• The braces must be the first and last characters of the value. {a}px and two references in one value are invalid.
• A reference must name a token. {color} is invalid if color is a group, even one with a $root token, and {color.$root} is refused because the DTCG reference pattern allows no $ in a segment. To reference a $root token, write a JSON Pointer in the JSON view: { "$ref": "#/color/$root/$value" }.

Whole tokens and single fields

The entire value can be a reference. $type is optional then, and the token takes its target’s type:

{ "$value": "{blue.500}" }

Or one field of a composite value can be a reference, with literals beside it:

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

Which field takes which type

Composite	Field	Reference to
border	color / width / style	color / dimension / strokeStyle
transition	duration, delay / timingFunction	duration / cubicBezier
shadow	color	color
shadow	offsetX, offsetY, blur, spread	dimension
gradient stop	color / position	color / number
typography	fontFamily / fontWeight	fontFamily / fontWeight
typography	fontSize, letterSpacing / lineHeight	dimension / number
strokeStyle	dashArray items	dimension
cubicBezier	Each of the four numbers	number

inset on a shadow takes no reference, because DTCG has no boolean type. The token dialog lists tokens of the matching type, except that a font weight field also lists number tokens, which then give a type mismatch. A mismatch written by hand is saved, and the token then shows No value.

JSON Pointer references

In the JSON view you can read one property of another token with $ref:

{ "$type": "number", "$value": { "$ref": "#/border/$value/width/value" } }

A group can inherit another group’s tokens with $extends, for example "$extends": "{palette}". A token that uses a JSON Pointer reference opens in the JSON view, not the token dialog.

Resolution

A reference resolves after the token sets are composed, so it takes the winning definition under the themes in use. That is how {brand.primary} can differ per theme.

References may chain. A cycle is saved, but the tokens in the loop have no value.

Broken references

A red link icon on a row marks a token with no value. The tooltip gives the reason.

Tooltip	Meaning	Fix
Broken reference: {x} does not exist	No token set defines the target	Create the target, or edit the reference
Broken reference: it refers to a token whose reference is broken	Something further down the chain is broken	Fix that token
No value: {x} has no value in this theme	The target exists, but not in the sets of this theme	Add it to a set of this theme
No value: another reason	A cycle, a type mismatch or a similar problem	Fix what the tooltip names

A token with a broken reference cannot be applied to layers or synced to Figma variables. Exports warn and keep the reference as written.

What protects references

Syntope Engine checks every change against all token sets, used by a theme or not.

Action	Result
Saving a reference to a name no set defines	Refused
Renaming a token that others refer to	Refused unless another set defines the old name. References are not rewritten
Deleting a token or set that others refer to	Refused, with a separately confirmed force delete
Deleting what a group’s $extends needs	Refused, with no force delete. Remove the $extends first
A JSON save or import that would break a reference	Refused
Renaming a token set	No effect, references do not name sets

Force delete is the only way to create a broken reference. Undo restores the deleted token and its references while the plugin stays open.

A worked example

primitives/color     blue.500             a literal
primitives/color     violet.500           a literal
brand/acme           brand.primary        {blue.500}
brand/globex         brand.primary        {violet.500}
semantic/color       action.default       {brand.primary}
component/button     button.background    {action.default}

Put brand/acme and brand/globex in two themes of one theme group. Switching the theme changes button.background, and nothing else needs editing.