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.
The plugin requires Figma desktop (version 116+) or Figma in a Chromium-based browser. Safari is not supported.
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.
The plugin remembers your last selected project and branch per Figma file, so you pick up right where you left off.
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.
Push requires the Designer or Admin role and a Pro plan or above. Developer accounts and Free plan users can only pull.
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.
Scope changes made directly in Figma's variables panel require an explicit Push (or Sync) to be recorded on the platform branch — just like value changes.
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) to focus on just the tier you need. The token form adapts per tier: primitives show a raw value input, semantics show a reference picker, and compositions show a structured property editor.
Browsing tokens is available on all plans. Creating, editing, and deleting tokens in the plugin requires a Pro plan or above.
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, or Composition) to assign to the entire batch.
Requesting reviews
Token Requests and branch management in the plugin require a Team plan or above.
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.
Chips are disabled when no layer is selected on the canvas. Pull tokens first for full Figma Variable binding — without a prior pull the inspector still applies the resolved value directly, but the layer will not be linked to a Figma Variable.
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.
Free plan projects are limited to one named theme. Pro plans and above support unlimited themes per project.
Pull your tokens at least once before applying a theme — this creates the Figma Variables that theme overrides will be applied to.
Publishing releases
Releases are available on every plan, including Free. Only admins and designers can publish.
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").