Getting started

Particles UI is a design token platform for teams. Create tokens in the Studio or Figma, version them like code, and publish them everywhere — components, themes, and codebases 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

Concept	What it means for you
Project	Your design system — a collection of tokens, themes, and branches.
Token	A named design decision (colour, spacing, radius…) organised by type and tier.
Branch	A sandbox for experimenting. Changes stay isolated until you request a review.
Token request	A review of your branch changes — like a pull request, but for design tokens.
Theme	A named variant of your design system (e.g. Dark, Brand A) that overrides specific tokens.
Release	A published, immutable snapshot of your tokens — designers can pin a version in Figma.

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 and 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.

token values

# 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.

Team roles

Role	What you can do
Admin	Full access — manage members, approve requests, publish releases, configure billing.
Designer	Create and edit tokens, branches, and themes. Open and review token requests.
Developer	Read access to tokens and exports. Pull via CLI and API.

Permissions apply consistently across Studio, the Figma plugin, and the CLI — your role follows you everywhere.