Figma plugin

The Particles Figma plugin is your primary design surface for tokens — pull the latest approved tokens into your Figma file, push design changes back to the platform, and manage branches and reviews without leaving Figma.

Installing the plugin

Open the Particles UI plugin page on the Figma Community and click Install.

Signing in

When you open the plugin for the first time, click Sign in — a browser window opens where you approve the connection. Your credentials are never handled by Figma; the plugin uses a secure one-time authorisation flow.

After approval, your session is stored automatically. You will stay signed in across plugin sessions — no need to log in again unless your session expires.

Choosing a project and branch

After signing in, select your organisation and project from the dropdowns at the top of the plugin. Then choose a branch — by default you work on main, but you can create a new branch inline by clicking the + button next to the branch selector.

Pulling tokens into Figma

Pull fetches all tokens from the selected branch and applies them as Figma Local Variables, organised in a collection named after your project.

Pulling is additive — existing Figma variables are updated in place, and new tokens are created automatically. Tokens deleted from the platform are not removed from Figma; use Clean up orphans in plugin settings to remove them.

Composition typography tokens are handled separately: instead of creating individual variables, they generate Figma Text Styles named Particles UI/<tokenPath> — bundling font family, size, weight, line height, and spacing into a single reusable style.

Pull also applies each token's variable scope — controlling which design properties the variable appears in across your Figma file. Tokens with no stored scope fall back to a sensible platform default for their type.

Pushing your design changes

Push reads your current Figma variable values, compares them to the branch, and shows a confirmation dialog listing every change. Each entry indicates whether a value changed, a scope changed, or both. Review the diff, add an optional commit message, and confirm.

Scope change notifications

The plugin monitors your Figma file automatically. When it detects that a variable's scope has changed in Figma's native variables panel, a banner notification appears — the same flow used for value changes. The banner shows how many variables changed by value and how many by scope only.

Rows in the notification list show a scope badge for scope-only changes. Clicking Sync to platform opens the confirmation dialog where you can review all changes before saving them to your branch.

Managing tokens in the plugin

The plugin provides full token management — browse, create, edit, and delete tokens from a list grouped by type. Use the tier filter tabs (All / Primitive / Semantic / Composition / Component) to focus on just the tier you need. The token form adapts per tier: primitives show a raw value input, semantics and components show a reference picker, and compositions show a structured property editor.

You can also import tokens directly from a JSON or CSV file — Tokens Studio JSON, W3C Design Tokens, Particles JSON, or CSV. The plugin shows a preview of changes (added, overwritten, and skipped counts) before applying. For non-Particles formats, choose a tier (Primitive, Semantic, Composition, or Component) to assign to the entire batch.

Make Scalable turns a flat or messy token set into a layered primitive → semantic system without leaving Figma. A review table shows each token's proposed target with a match indicator; retarget or skip any row, then apply — the change is non-breaking (names and ids preserved, values identical) and your bound Figma variables follow by token id. A Revert last run button restores the pre-migration state. See Make Scalable in the Tokens docs for the full behaviour.

Tokenize Design

Make Scalable refactors tokens that already exist; Tokenize Design is for a Figma file that never used variables at all. Open it from the Tokens view: pick a scope — This page or Selected nodes — and the plugin scans for unbound raw values (fills, strokes, effect colours, spacing, radius, stroke weight, font size & family). It names them into a scalable primitive → semantic set, then shows a review where you can rename or skip rows, merge near-identical colours, and read a live “create N · rebind M” tally.

You can also pull a colour palette straight from an image — select a frame with an image fill and choose From image, and a vision model reads the scale. On apply, the plugin creates the variables in your project's collection and rebinds every matching node in the chosen scope — rendered values never change. A “Rebind to” control lets you target the whole page or just your current selection, and an optional toggle saves the new tokens back to the project so they round-trip with Pull.

Requesting reviews

If you are working on a branch, open a token request to propose your changes for review. The plugin lets you:

Create a request with a title and target branch. View the request list with status badges (open, approved, rejected, merged). Open a request detail to read comments and take Approve, Reject, or Merge actions (role-gated). Post new comments on any request.

Token inspector & quick apply

Select any layer on the Figma canvas and switch to the Inspector tab. The inspector connects directly to the platform — it fetches your project's tokens live so chips are always up to date with whatever branch you have selected.

Token chips are organised by tier (Primitive / Semantic / Composition) and category (Color, Spacing, Typography, etc.). Use the search bar to filter across all categories. Clicking a chip instantly binds the token to the matching design property on your selected layer. If you have pulled tokens, the layer links to the Figma variable — so changes in Studio flow through automatically. Categories with multiple binding targets show property filter pills below the category row — Color shows Fill, Stroke color, and Shadow color filters. Typography composition chips apply the matching text style to your selected layer.

Named themes

The Themes tab lists all named themes for the selected project (e.g. "Dark", "Brand A"). You can create a new theme inline from the plugin — the theme is immediately available in the Studio as well.

Click Apply to Figma on any theme to apply its token overrides as a Figma Variable Mode. On Professional+ Figma plans, the plugin adds a new mode to your existing collection. On Starter plans (limited to one mode per collection), the plugin creates a separate collection named Particles UI [theme name] so the theme overrides remain accessible.

Publishing releases

Admins and designers can publish a versioned release directly from the plugin. Select a branch, enter a version number (e.g. 1.2.0), and add optional release notes. The release is an immutable snapshot that team members can pull later to review or roll back to a specific version.

The release list shows all versions in descending order. Use Pull release to import a specific version's token snapshot into Figma as a named variable collection (e.g. "MyProject v1.2.0").

Guidelines panel

Select any component on the canvas and open the Guidelines tab in the plugin. If the component has a published documentation page in Particles, it renders inline — usage guidelines, anatomy diagram, do/don't examples, and WCAG contrast checks — all read-only, always reflecting the live version from your current branch.

Use the search bar inside the Guidelines tab to find any doc page by keyword or semantic intent without leaving Figma. Results link directly to the relevant section so you can read the specification for any component or token in context.

Troubleshooting