Figma plugin
The Particles Figma plugin is your primary authoring surface for design 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
Search for Particles UI in the Figma Community and click Install. Once installed it appears under Plugins → Development → Particles UI.
The plugin requires Figma desktop (version 116+) or Figma in a Chromium-based browser. Safari is not supported due to restricted iframe communication.
Signing in
When you open the plugin for the first time, you will be prompted to sign in. Click Sign in — a browser window opens where you approve the connection. Your credentials are never handled by Figma; the plugin uses a secure device 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 token 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. Colour tokens become Figma colour variables; spacing, radii, and other numeric tokens become number or string variables, all organised in a Figma Variable 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 during pull: instead of creating Figma Variables, they generate Figma TextStyles named Particles UI/<tokenPath>. Within each TextStyle, fontFamily, paragraphSpacing, and paragraphIndent are bound as Figma variable chips (visible in the type panel), while fontSize, lineHeight, and letterSpacing are set as direct values. Primitives and semantics are processed before composition tokens during pull.
Pushing your design changes
Push reads the current Figma variable values, compares them to what is on the branch, and shows you a confirmation modal listing every change. Review the diff, add an optional commit message, and confirm.
Push requires the Designer or Admin role. Developer accounts can only pull.
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.
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 dry-run diff (added, overwritten, and skipped counts) before committing changes. For non-Particles formats, choose a tier (Primitive, Semantic, or Composition) to assign to the entire batch. Particles JSON files preserve the original per-token tier automatically.
Requesting reviews
If you are working on a branch that targets main, 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 in the active tier by token path or property name — category pills hide while a query is active. Clicking a chip binds the token to the matching Figma property using a three-tier lookup: first, the tokenId is matched against the in-memory variable map from the latest pull; second, against the persisted token_var_names map in Figma clientStorage (survives plugin reloads); third, if no variable is found, the resolved value is applied programmatically as a direct hex or number — a toast prompts you to pull for full variable binding. Categories with multiple binding targets show property filter pills below the category row — for example, Color shows Fill, Stroke color, and Shadow color sub-filters drawn from the chip data. Composition chips find the pre-created TextStyle by name (from PULL_TOKENS) and apply textStyleId directly to the selected layer, creating a TextStyle on-the-fly only as a fallback.
Chips are disabled when no layer is selected on the canvas. Pulling tokens first enables 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.
Publishing releases
Admins and designers can publish a semver-tagged 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 QA 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").