Token sets

A token set is a slash-separated path that groups tokens. Sets are the unit that themes switch and that folder export writes as files, so how you cut them determines how flexible your system is later.

---

Creating a set

new token set at the bottom of the tree, or the empty-state button on a fresh document.

global/color
brand/acme/color
mode/dark
comp/button

Paths are stored lowercase. Enter submits.

Error	Cause
Enter a folder or file path.	Empty input
Token set already exists.	Duplicate path

---

Managing sets

Right-click a set in the tree:

Action	Behaviour
Rename	Changes the path. Tokens stay in the set
Duplicate	Clones the set under a new non-clashing path, including all its tokens
Delete	Removes the set and every token in it. Confirmation required, and it cannot be undone

The tree shows a token count per set and a checkbox indicator that is filled when the set is enabled by an active theme.

---

A structure that scales

The three-tier convention below is the one most design systems converge on. It is a recommendation, not something the plugin enforces.

global/
  primitives/color        raw palette — blue.500, neutral.900
  primitives/spacing      raw scale — 0, 1, 2, 4, 8…
  primitives/typography   raw families, sizes, weights

semantic/
  color                   surface.default, text.muted, border.subtle
  spacing                 space.inline.sm, space.stack.lg
  typography              heading.lg, body.default

comp/
  button                  button.bg.default → {semantic.color.action}
  input
  modal

Each tier references the one above it. Primitives hold literals; nothing else does.

Why it pays off: rebranding touches only global/primitives. A dark mode is a second semantic/color set. A component restyle touches one comp/ file.

Axis sets

Anything a theme should switch gets its own set:

brand/acme/color
brand/globex/color
mode/light
mode/dark
density/compact
density/comfortable

A theme then enables one set per axis. See Themes.

---

Naming: set path vs token name

This trips people up:

	Separator	Example
Token set path	/	global/primitives/color
Token name	.	blue.500

The full token path is the two joined. In folder export, the set becomes the directory structure and the name becomes the JSON nesting.

---

How sets map to files

Folder export writes one JSON file per set, nested by path:

design-tokens.zip
├── global/
│   ├── primitives/
│   │   ├── color.json
│   │   └── spacing.json
│   └── semantic/color.json
├── comp/button.json
└── $themes.json

Inside each file the set prefix is stripped from the token names, so a folder export → folder import round trip is lossless. Tokens without a set land in tokens.json.