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 four tiers#

Particles organises tokens into four 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.

Component — component-scoped tokens

Component tokens are the most specific tier: values tied to a particular UI component, such as button/background or card/padding. They reference a semantic token (or hold a structured value) so a single semantic change cascades to every component that uses it — without coupling components to raw primitives.

button/background  →  {color.primary}
button/radius      →  {radius.md}
card/padding       →  {spacing.4}

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.

Token policy

Projects can define a write-time token policy (Protection settings, org admins): a naming pattern with optional per-tier overrides, a required description, semantic-must-alias (semantic tokens must reference, never hold raw values), and an allowed-units list for dimension tokens like spacing, radii, and breakpoints. Saving a token that violates the policy fails with HTTP 422 POLICY_VIOLATION, listing each broken rule. Imports are never blocked by policy — the import diff carries a non-blocking policyWarnings list instead, so legacy files can land first and be cleaned up inside the governed editor.

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.

Make Scalable — refactor a flat set into tiers#

Inherited a token set that is one flat layer of hard-coded values — or a Figma file where every colour was created as a raw variable with no structure? Make Scalable turns it into a proper primitive → semantic system without rewriting anything by hand.

It respects the structure you already have: tokens that were already primitives are kept verbatim — including your own family names like brand-lime-800 — and only genuine semantics are re-pointed. Nothing is renamed, deprecated, or deleted, and every rendered value stays identical, so the change is non-breaking.

Where to run it

Prefer to migrate onto a brand-new, cleanly named set instead of refactoring in place? That is a different flow — particles migrate --scalable — which mints the new set and rewrites your legacy tokens into deprecated aliases pointing at it. See the CLI reference for when to use which.

Tokenize Design — bootstrap tokens from a raw Figma file#

Make Scalable refactors a token set that already exists. Tokenize Design is the step before that — for a Figma file that never used variables at all, where every colour, spacing, radius, and font is a hard-coded raw value. It runs in the Figma plugin: scan the page (or just your selection), name everything into a clean primitive → semantic set, create the variables, and rebind the nodes — with rendered values preserved exactly.

The rebind is value-driven: it binds every node whose value matches a new token, not just the ones the scan enumerated — so a palette read from an image still rebinds the matching layers on your canvas. Choose This page or Selected nodes for the rebind scope; a selection-scoped run never touches anything outside your selection.

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.