figma_import_tokens
Imports DTCG design tokens from your codebase into Figma as variables, applying diff-aware create, update, and delete changes so code and design stay in sync.
Instructions
Push design tokens from your codebase into Figma as variables. Bidirectional with figma_export_tokens.
ACCEPTS: DTCG JSON (canonical, fully supported including round-trip metadata preservation). Tokens Studio JSON, CSS custom properties, Tailwind v4 @theme, SCSS, and Style Dictionary v3 are scaffolded but return a NotImplementedError — convert to DTCG first via figma_export_tokens or hand-author DTCG. Use format: "auto" to sniff the input.
APPLY PHASE (full bidirectional sync): toCreate entries create missing collections (with the token file's full mode list) and missing variables in one batched plugin round-trip — literal values first, alias values in a second pass so aliases between newly-created variables resolve. toUpdate entries push value updates in a batched round-trip, INCLUDING alias-target updates: when a token's value is a reference, it's written as a Figma variable alias if the reference resolves to an existing or just-created variable (unresolvable references skip with a warning). toDelete entries are STRICTLY gated behind strategy: "replace" — in replace mode, Figma variables absent from the token file are permanently deleted (a loud warning lists the count); merge (default) preserves them and only reports. Deletes only ever touch collections the token files contain: variables in collections the import doesn't include are left alone. An import that parses 0 tokens is refused, and the diff is computed against live Figma state. Motion tokens are written as TIMING (DTCG duration; a bare number is milliseconds) and EASING (DTCG cubicBezier) variables; springs and holds round-trip through $extensions["figma-console-mcp"].spring. Variable scopes and per-platform codeSyntax (from $extensions["figma-console-mcp"].scopes/.codeSyntax) are diffed and applied too — absent fields mean "no opinion" (Figma-side metadata is preserved), an explicit value is authoritative. Partial-success semantics: per-item errors surface in applyResult.errors[] without failing the batch.
DIFF-AWARE: Default strategy: "merge" diffs against current Figma state and applies only deltas. The hacked-color scenario — designer edits one hex value in their CSS — produces exactly one Figma API update, not a full collection rewrite. Match priority: Figma variable ID (in $extensions["figma-console-mcp"].variableId), then exact token path, then value fingerprint.
CONFLICT HANDLING: When BOTH Figma and code changed the same token since the last sync, onConflict: "ask" (default) surfaces the conflict and writes nothing. Use figma-wins / code-wins to auto-resolve, or skip to leave conflicts alone and proceed with the rest.
DRY-RUN: Default first call after detecting changes is dry-run for safety. The response includes the full diff plan; user confirms, then call again with dryRun: false (or strategy other than dry-run) to apply.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Multi-file import (used for Tokens Studio's split-set format, or for projects with many DTCG source files). Mutually exclusive with `payload` and `configPath`. | |
| dryRun | No | Shorthand for strategy: 'dry-run'. Computes the diff and returns a preview without applying any changes to Figma. | |
| format | No | Format of the input payload. 'auto' (default) detects from payload shape or file extension. Pass an explicit format if auto-detection misfires. | |
| prefix | No | Prefix to strip from input token names on import. E.g. with prefix 'ds-', a token named '--ds-color-primary' becomes 'color/primary'. | |
| payload | No | Single-file content to import. Use this for one-shot imports without setting up tokens.config.json. Mutually exclusive with `files` and `configPath`. | |
| strategy | No | How to apply changes. 'merge' (default) diffs against current Figma state and applies only deltas, preserving Figma-only variables. 'replace' wipes the target collections and rewrites. 'dry-run' computes the diff and reports without touching Figma. | |
| configPath | No | Explicit path to tokens.config.json. When omitted, the tool autodiscovers and uses the config's source.dir to find files. Mutually exclusive with `payload` and `files`. | |
| onConflict | No | How to resolve true two-sided conflicts (both Figma and code changed the same token since last sync). 'ask' (default) surfaces the conflict and writes nothing. 'figma-wins' / 'code-wins' apply the corresponding side. 'skip' leaves conflicted tokens alone but proceeds with the rest. | |
| modeMapping | No | Map input mode names to Figma mode names. Useful when source uses 'light'/'dark' and Figma uses 'Light'/'Dark'. Defaults to 1:1 mapping with case preservation. | |
| collectionMapping | No | Map input token set names to Figma collection names. Example: {'primitives': 'Primitive Tokens'}. When omitted, set names map 1:1 to collection names. |