Tokens

Design tokens are the named 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 a colour value 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, and so on.

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   →  #f9f9f7
color/neutral-900  →  #1a1a18
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, each composition token becomes a ready-to-use CSS class in your codebase — 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 link one token to another — for example, {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.

Figma variable scope

Every token that maps to a Figma variable can carry a scope — a setting that controls which design properties the variable appears in. Scopes are stored alongside the token value and applied automatically when you pull tokens into Figma.

Scopes keep your variable picker tidy: a spacing token scoped to "gaps" will appear when setting auto-layout gaps but not when choosing fill colours — exactly where it belongs.

Where each token type appears in Figma

Setting scopes in the Studio

Open any token in the token editor. When the token type supports scopes, a Figma scope field appears at the bottom of the inspector panel. Click the scope chips to toggle which properties are active — chips with a dot indicator are the recommended defaults for that type. Deselecting all chips falls back to the platform default on the next pull.

Setting scopes in the Figma plugin

The plugin token form includes the same scope chip selector. Changes are saved back to the platform with the token value. On the next Push, scope changes appear in the review diff alongside value changes — so you can tell a scope-only change apart from a value change in the confirmation dialog.

Scope auto-detection on import

When you import tokens from an external file, Particles automatically infers the right scope from the token's name and group path. For example, a colour token named background defaults to fills; a token named text defaults to text color. You can adjust any inferred scope after import.

Figma sync

When you Pull, scopes are applied to each Figma variable automatically. When you Push, both value changes and scope changes are tracked independently — each appears as a separate entry in the review dialog. If you edit a variable's scope directly in Figma's variables panel, the plugin detects the change and surfaces a notification banner, just like a value change.