Tokens

Design tokens are the atomic decisions that power every visual property in your design system — colours, spacing, typography, radii, and more. Particles stores, versions, and distributes them so your team always works from a single source of truth.

What is a token?

A token is a named design decision. Instead of hard-coding #3366FF in ten different places, you create a token called color/primary and reference it everywhere. When your brand colour changes, you update the token once and every surface updates automatically.

In the Studio token editor, each token shows its name, type, current value, and a live preview (colour swatches for colour tokens, scale labels for spacing, etc.).

The three tiers

Particles organises tokens into three tiers — what you are defining determines which tier you use:

Primitive — raw values

Primitives are your base palette. They hold an exact, final value with no references to other tokens. Think of them as your raw materials — brand colours, spacing scales, radii.

color/neutral-50   →  oklch(0.98 0 0)
color/neutral-900  →  oklch(0.09 0 0)
spacing/1          →  0.25rem
radius/md          →  0.5rem

Semantic — design intent

Semantic tokens give a meaning to a primitive. Instead of saying "use neutral-900," you say "use background." This lets you swap the entire palette without changing any component references.

color/background   →  {color.neutral-900}
color/foreground   →  {color.neutral-50}
color/border       →  rgba(226, 226, 226, 0.12)

Composition — bundled styles

Compositions bundle multiple properties into one named style — like a typography heading that includes font family, size, weight, and line height. Each property can reference another token or hold a raw value.

# Typography composition: "heading-1"
fontFamily    →  {font.sans}
fontSize      →  {spacing.8}
fontWeight    →  700
lineHeight    →  1.2

When exporting to Tailwind v4, composition tokens are emitted as @utility blocks outside the @theme {} block — not as CSS custom properties — so each composition becomes a usable utility class in your Tailwind project (for example, .heading-1 applies all bundled typography properties at once).

Token types

Every token has a type that determines what kind of value it holds. 16 built-in types are created automatically when you set up a project:

Need something custom? Under Project → Settings → Token types you can add project-specific types beyond the 16 built-ins.

Sub-groups

Tokens within a type can be organised into named sub-groups — for example, grouping your neutral colours under color → neutral and your brand colours under color → brand. This produces clean CSS variable names like --color-neutral-50 and keeps your token tree scannable.

Create groups from the token editor by clicking the + button next to a type header. When creating a token, select its group from a dropdown.

Creating and editing tokens

In the Studio token editor, click New token and fill in:

The token form adapts based on the tier you select: primitive shows a plain value input, semantic shows a reference picker that only shows tokens of the same type, and composition shows a structured property grid.

How references resolve

When you reference another token with curly-brace syntax like {color.neutral-900}, the platform resolves the full chain automatically. A semantic token pointing to a primitive immediately shows the resolved value. Circular references are rejected on save.

Accessibility & contrast

Particles can compute WCAG contrast ratios between any two colour tokens. In the token detail form, tag a pair as foreground/background, and the Studio displays the contrast ratio with AA/AAA pass/fail badges. Failing pairs show the nearest compliant alternatives.

Your organisation admin can view a company-wide Accessibility Dashboard that aggregates all failing pairs across projects.