Getting started

Particles UI is design decision infrastructure for teams. Create tokens in the Studio or Figma, version them like code, and publish them everywhere — codebases, themes, and AI agents stay in sync automatically.

How it works#

A design token is a named decision — a colour, a spacing unit, a border radius. Particles stores these decisions centrally so designers and developers always work from the same source of truth.

Designers author tokens in the Studio web app or the Figma plugin. Changes happen on branches and reach the main token set through a review process — nothing ships without a second pair of eyes. Developers consume the approved tokens via the CLI or API.

Key concepts#

Quick start#

1. Create your project

Sign up at studio.particles-ui.com/login. You will be prompted to create an organisation and your first project. An organisation is a shared workspace for your team.

2. Add tokens in the Studio

Open your project in the Studio — it lands in read-only browse mode. Click Start a change in the topbar, give it a name and a short intent, and the editor unlocks. Now click New token: give it a name, choose a type (colour, spacing, radius…), and set a value. Primitives hold raw values; semantic tokens point to a primitive by name — just wrap the token name in curly braces to create a link. See Changes & governance for how changes and browse mode work.

# Primitive — raw value
color/neutral-900  →  #1a1a18

# Semantic — links to a primitive by name
color/background   →  {color.neutral-900}

# Composition — bundles multiple properties
typography/heading-1 → fontFamily: {font.sans}, fontSize: {spacing.8}

3. Connect Figma (optional)

Install the Particles UI plugin from the Figma Community. After a one-time sign-in, you can pull tokens directly into your Figma variables and push design changes back to the platform — no copy-pasting hex values.

4. Share with developers

Once your tokens are approved and merged into main, engineers on your team can pull them into their codebase using the CLI:

# Authenticate once
particles auth login

# Interactive setup — select org, project, format, and output path
particles init

# Pull the latest published release (default — like npm install)
particles token-studio sync

# Pull from a branch during active development
particles token-studio sync --branch my-branch

# Export in a specific format to stdout or a file
particles token-studio export --format css --output ./src/styles/tokens.css

By default sync pulls the latest published release — stable and immutable, just like a versioned npm package. Use --branch to pull live changes during development before a release is cut. Tokens are sorted alphabetically by type and name to match the order in the Studio token list.

Migrating existing tokens (optional)

If your team already has a token file — whether it's a .json, .css, .scss, .ts, or .js export from another tool — Admins and Designers can push it directly into the project without having to re-create tokens manually in the Studio:

# Dry-run first to see what will change
particles token-studio push --file ./tokens/design-system.json --dry-run

# Apply the push
particles token-studio push --file ./tokens/design-system.json

On Team and Business plans, new projects start with main protected. The very first push into an empty main still works — onboarding a fresh project is always allowed — but once main has tokens, pushes to it are rejected: push into a change branch instead and send it for review (org admins can also push directly, audited as a hotfix).

Push detects the format from the file extension and maps it to the project's token model. See the CLI reference for the full list of supported formats and options.

Team roles#