Import Variables & Styles from Figma
Import local variable collections and styles from the current Figma file into plugin JSON tokens: choose collections and style groups, import behavior, optional config.json generation, diff-id updates.
Purpose
Import variables & styles (Tokens tab, bottom panel) is the reverse of export: from local variable collections, modes, and local styles (Paint / Text / Effect / Grid) the plugin builds DTCG-compatible JSON and may update config.json and diff-id.json.
Import runs only in the open file (Plugin API), not via REST.
How to open
- Open the Tokens tab.
- At the bottom of the file list: Import variables & styles (after Export).
The action works without config.json: use Smart or Generate (see mapping modes below).
Scope selection
- Variable collections — local collections (same inventory source as Destructive in the export modal). The section header toggles all.
- Style groups — first path segment of style names (
Group/Name→ groupGroup).
If the list is non-empty, you must select at least one collection or group (or use the header to select all); starting import with nothing selected is blocked.
Type filters
Variables and Styles chips mirror export semantics: only enabled types are imported (all on by default).
Collection mapping: Smart / Strict / Generate
Three modes match the chips in the modal:
| Mode | Behavior |
|---|---|
| Smart (default) | Reads config.json and keeps configured paths; for selected collections adds missing collections, modes, and files (greenfield fill when a mode has no enabled files); merges ref for aliases. A successful merge may persist an updated config. |
| Strict | Only paths already declared in config.json; unknown collections/modes are skipped with warnings; the config is not expanded automatically. |
| Generate | Full greenfield layout for the selected collections: new token paths and overwrites the collections section of config.json. |
If Strict is selected but the project has no valid config.json, import is blocked until you switch to Smart or Generate.
Other import options
| Option | Meaning |
|---|---|
| Multi-file layout (greenfield) | With Generate (and with Smart when greenfield files are added for an empty mode): each mode gets either a single tokens.json or a split set (colors.json, typography.json, …). |
| Overwrite existing token values | Off = new paths only (merge-only); on = overwrite leaves with $value. |
| Preserve variable aliases | VARIABLE_ALIAS → {path}; off = literals when possible. |
| Map Figma scopes → $extensions | Best effort from API scopes. |
| Update diff-id.json | Hashes and Figma ids for export round-trip. |
| FLOAT → dimension | FLOAT semantics: dimension vs number. |
Where files land
- With Smart / Strict and a working map — writes go to
modes[].files(relative to the token root), with heuristic file choice per mode. - With Generate and when Smart adds greenfield paths — token tree under
<collection-slug>/<mode-slug>/…(no_import/prefix). Styles without a config route may usestyles/imported-styles.json. - Styles with variables:
boundVariableson fills, typography, effects (color, offsets, blur, etc.) serialize to{path}aliases the same way as variables, respecting Preserve aliases.
Limitations
- Reverse mapping of gradients and complex effects may need manual JSON fixes.
- Collection/mode names must align with the config (unless you generate a new one).
- Published library variables outside local collections may trigger warnings when resolving aliases.
Engineering details
See Plugin/docs/ru/20-import-from-figma.md.