Core concepts

The terms below come from the DTCG specification and from the data model of Syntope Engine. The rest of this documentation uses them as defined here.

Token set

One complete DTCG Format document with a location such as foundation/color.

• Each / in the location adds a folder in the sidebar of Syntope Tokens, the Figma plugin.
• In a project folder, a set is one file: foundation/color becomes tokens/foundation/color.tokens.json.
• Base and themes switch whole sets on and off.

The location is an address, not part of a token’s name. Moving a set from foundation/color to brand/color renames no token.

A DTCG Resolver also has “sets”, but those are ordered lists of documents. In this documentation, a token set always means one document.

→ Token sets

Token path

A dot-separated name inside one set, such as color.brand.primary. Each dot is a DTCG group, and the last segment is the token. The field in the token form is labelled name and takes the path without the set.

A segment cannot contain {, } or \, and cannot start with $.

Two sets can define the same path. Both definitions stay stored and editable, and neither replaces the other. Which one wins is decided each time sets are composed.

{
  "color": {
    "brand": {
      "primary": {
        "$type": "color",
        "$value": { "colorSpace": "srgb", "components": [0.1, 0.4, 0.9] }
      }
    }
  }
}

→ Token types

Base

The ordered list of sets that always apply. Later sets override earlier ones.

Base is automatic: a set that belongs to no theme is in Base, unless you untick it under base token sets on the themes tab. Unticking keeps the set and its tokens, and only leaves them out of the result.

In a DTCG Resolver file, Base is the first set in resolutionOrder.

Theme group

A named choice such as mode or brand. In DTCG terms, a Resolver modifier.

Theme groups apply after Base, from top to bottom, so a later group overrides an earlier one. A group needs at least two themes to take effect. A group with one theme is kept but not applied, and the themes tab says so.

Theme

One option of a theme group, such as dark. In DTCG terms, one context of a modifier. A theme is an ordered list of sets, and the last listed set wins.

One theme per group is in use at a time. The one you switch on is the project default: it decides which values the plugin applies to layers.

A set is either included or not. There is no state where a set only serves references.

Base          foundation/color, foundation/space     always
mode          light | dark                           one of these, after Base
brand         brand-a | brand-b                      one of these, after mode

→ Themes

References

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

{ "$type": "color", "$value": "{color.brand.primary}" }

A reference names a token path, never a set. It resolves after the sets are composed, so one reference can give a different value in each theme. It can stand for a whole value, or for one field of a composite value such as the color of a border.

The engine protects references:

• A delete that would break a reference is refused and names the tokens that depend on it. The plugin also offers force delete, which asks again and leaves those references broken.
• A token rename or move that would break a reference is refused and cannot be forced. Do instead: create a token under the new name, point each dependant at it (view dependencies finds them), then delete the old token. Layers bound to the old token need the new one applied.

→ References and aliases

Stable IDs

Token sets, tokens and theme groups have internal IDs that do not change. Names and paths can change without creating a new object. A rename in the plugin or through an AI app keeps the ID, so bindings and links to Figma variables stay intact.

Token IDs are not written to files. On a pull or an import, a token is matched by its path inside its set. A token renamed directly in Git therefore arrives as a new token, and the old one is removed. The review lists the removal and counts the layers bound to it. Do instead: rename tokens in the plugin or through an AI app, then push.

Bindings

When you apply a token, the plugin records a binding on the layer: which token, by its stable ID, on which property. A binding is private plugin data on that layer.

A binding is a record, not a live link. Editing a token does not change layers. Do instead: select the layers and choose sync to: selection in the plugin footer, which applies the current values again.

→ Applying tokens, Inspecting bindings

How they fit together

Token set  foundation/color
└── color.brand.primary     $type: color   $value: { "colorSpace": "srgb", ... }
          ▲
          │ {color.brand.primary}          reference
          │
Token set  component/button
└── button.background       $type: color   $value: {color.brand.primary}
          │
          │ Apply token → fill
          ▼
Figma layer  "Button/Primary"              binding stored on the layer

Base and the theme in use decide which sets take part when the reference resolves.