Round-trip import

Click Import in the plugin UI. Pick a ZIP (or individual JSON files); the plugin runs in two phases.

PreviewLink to this section

Before applying anything, the plugin reads manifest.json and classifies every incoming variable:

• Matched — same name + same Figma type. Will be updated (value changes only — type/scope are preserved).
• New — name not seen before. Will be created.
• Unmatched-existing — variables already in Figma but absent from the import. Kept by default; can be flagged for deletion via the UI.

The preview UI shows per-collection counts (newVars, updatedVars, totalVars) and lists variable names so you can review before applying. Mode mappings are also surfaced — if Figma's mode names differ from the export's (e.g. local file has "Light", export has "default"), you pick which incoming mode maps to which existing mode.

ApplyLink to this section

After confirming the preview, the plugin runs four steps:

1. Import variables — creates new variables, updates matched ones, applies mode mappings. References ({primitives.gray.900}) are resolved against the live Figma variable graph.
2. Import text styles — creates / updates local text styles from text.styles.tokens.json.
3. Import effect styles — creates / updates from effect.styles.tokens.json.
4. Import grid styles — creates / updates from grid.styles.tokens.json.

The plugin guards against silent overwrites:

• Every variable creation/update is explicit.
• The manifest's generator.name is verified to be @systhemaui/figma (rejects imports from other tools).
• Type mismatches between incoming and existing variables produce a "rename" or "skip" prompt rather than a silent destruction.

This round-trip path is what makes the plugin safe to use as two-way sync — a designer can hand JSON to a developer, the developer can edit (e.g. via a customTokens block in the project), and the result can be applied back into the Figma file without disturbing variables that aren't in the import.