Studio

Particles UI Studio is the web app where designers create, edit, and manage design tokens — your single source of truth for every visual decision in your design system.

What the Studio does#

The Studio brings your entire design token workflow into one place: author tokens, organise them by type and tier, create themes, review branch changes, and publish releases. Everything you do here automatically syncs to the Figma plugin and the CLI.

Projects#

A project is your design system — a collection of tokens, themes, and branches. When you create a project, Particles seeds sixteen built-in token types (Colour, Typography, Spacing, Radii, Shadow, Opacity, Border, Duration, Z-index, Elevation, Grid, Motion, Line Height, Letter Spacing, Font Weight, Breakpoint) and a main branch. On Team and Business plans, new projects start with main protected — edits reach it through reviewed changes, and org admins can toggle protection in Protection settings.

If you already have tokens in another tool, upload a file at creation time — Tokens Studio JSON, W3C Design Tokens, Particles JSON, or CSV — and your project is seeded with them immediately. Default example tokens are skipped so you start with a clean slate.

Projects belong to an organisation. Invite team members with roles (Admin, Designer, Developer) to control who can edit tokens and who has read-only access.

Token editor#

The token editor is govern-first. Opening a project lands you in browse mode: the left panel shows your whole token tree organised by type and sub-group, with a segmented control at the top to filter by tier (Primitive / Semantic / Composition / Component) — but every token is read-only. Click a token and you get an inspector, not an editable form.

To make a change, click Start a change in the topbar (or from the read-only inspector). Name the change, state your intent, and pick a base branch — this creates a working branch and unlocks editing. A Change Bar then docks at the bottom of the editor for the rest of the session: live edit count and diff, an ambient accessibility gate, Discard, and Request review. See Changes & governance for the full model.

Project rail#

Navigation inside a project is a grouped left rail, with an Overview landing page above the groups — a control-plane view of the project's tokens, branches, and health at a glance.

The Activity page pairs the per-branch audit log with the project's governance events feed — hotfix writes to protected main, gate blocks at merge or release, unreviewed merges, and ownership overrides, newest first with the actor and branch attached. See Changes & governance for the full event catalogue.

Releases#

A release is an immutable, versioned snapshot of all tokens on a branch — tagged with a version number (e.g. 1.2.0). Think of it as a published edition of your design system.

Creating a release freezes every token value at that point in time. Team members can pull a specific release in the Figma plugin to QA past versions, and developers can pin their codebase to a specific release version using the CLI:

# Sync a specific release snapshot to src/globals.css
particles token-studio sync --version 1.2.3

# Export a specific release in any format
particles token-studio export --version 1.2.3 --format css --output ./tokens.css

# Omit --version to always pull the latest from the branch
particles token-studio sync

Import & export#

Bring tokens in from other tools or export them for your build pipeline:

Import shows a preview of changes before applying — see exactly which tokens would be added, overwritten, or skipped, then confirm with Apply. For non-Particles formats, a tier selector lets you assign all incoming tokens to Primitive, Semantic, or Composition in one step. Particles JSON imports skip this step because tier is embedded in the file.

If the project defines a token policy, the preview also lists policyWarnings — incoming tokens that break the naming, description, alias, or unit rules. Warnings never block the import; they tell you what to clean up afterwards. Applying an import into a protected, non-empty main is rejected — import into a change branch instead (the first import into an empty main is always allowed, so seeding a new project just works).

Contrast checking#

Tag any two colour tokens as a foreground/background pair in the token detail form. Particles automatically computes the WCAG contrast ratio and displays AA/AAA pass/fail badges. Failing pairs show the nearest compliant alternatives.

The organisation-wide Accessibility Dashboard aggregates all failing pairs across every project so you can track compliance at a glance.

Docs tab#

Every token supports an optional description (markdown) and tags. The Docs tab renders all tokens with their descriptions as a living style guide, auto-grouped by type. Org admins can pin important tokens to surface them at the top of the tree.

Tags and descriptions are included in all export formats and CLI sync output, so developers see usage guidance directly in their codebase.

Permissions#