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 component mappings.
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 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 reference a primitive using curly-brace syntax.

token values

# Primitive — raw value
color/neutral-900  →  oklch(0.09 0 0)

# Semantic — references a primitive
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:

particles pull --project <project-id> --branch main

This writes a CSS file with all resolved token values, ready for Tailwind v4 or any build pipeline.

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.

Role permissions are enforced on the server. Passing a higher-privilege API key does not elevate access — roles are tied to your organisation membership.