Figma Token Assistant

A lightweight Figma plugin for design token discovery and migration. The MVP runs offline with a local JSON token fixture and supports migration suggestions for color, spacing, radius, and border width.

Features (v1.3.0)

• Token list with search and category filters (color, spacing, radius, border width, uncategorized)
• Apply tokens directly from the list to the current selection (with one-step undo)
• Migration scan for fills, strokes, spacing, radius, and border width
• Suggestions with apply-one or apply-all
• Variable binding when matching Figma variables (with fallback)
• Debug panel for migration/variable binding diagnostics
• Default token source from local Figma variables
• Import modal for library variables already used in the file and JSON tokens
• Manual reload button to resync tokens from the local file
• Import result view with revert support
• Categorize uncategorized tokens from the list

Getting Started

1. Install dependencies

npm install

2. Build plugin bundles

npm run build

3. Run tests

npm test

4. Load in Figma

• Figma → Plugins → Development → Import plugin from manifest
• Select manifest.json

Token Sources

Tokens are loaded from local Figma variables by default. Additional sources can be enabled via the import modal:

• Library variables already used in the file (read-only list).
• JSON paste or file import (validated and stored per file).

Notes

• The migration scan skips nodes that already have variables bound.
• When multiple tokens share the same value, migration suggestions prefer semantic/component tokens over primitives.
• If Figma does not apply boundVariables via API, the plugin assigns them manually to ensure variable badges appear.
• JSON import switches the token source filter to JSON import automatically.
• Numeric tokens with radius in their name can be inferred as radius when no category is provided.
• Imported JSON tokens are also stored in the Figma file as a fallback for persistence.
  • If JSON tokens are missing after reopening, use the Reload button to resync from file data.
• Imported tokens are stored locally (client storage + per-file plugin data) and never leave the user’s machine.
• UI message handling uses a soft check (presence of pluginMessage) because strict origin checks can break in Figma runtimes.

Scripts

• npm run build — builds UI and plugin code
• npm run lint — runs ESLint
• npm test — runs unit tests
• npm run typecheck — runs TypeScript checks