sync-figma-token

Original：🇺🇸 English

Translated

Sync design tokens between code and Figma variables with strict drift reporting, mandatory approval gate, safe delta apply, and persisted reports.

2installs

Sourcefirebenders/sync-figma-token-skill

Added on2026-03-25

NPX Install

npx skill4agent add firebenders/sync-figma-token-skill sync-figma-token

SKILL.md Content

View Translation Comparison →

sync-figma-token

Use this skill for token parity workflows (code tokens vs Figma variables).

MANDATORY prerequisite: load

figma-use

before every

use_figma

call.

Non-negotiable safety rule

After producing dry-run output, you MUST STOP and ask for approval.

Do NOT run any write
```
use_figma
```
calls in the same turn as dry-run output.
Ask a normal confirmation question (example: "Apply these changes? (yes/no)").
Only proceed on explicit affirmative approval.
If the response is unclear or negative, do not apply writes.

Standard source formats (required)

Prefer real token sources in this order:

Design Tokens JSON (
```
tokens.json
```
,
```
tokens/*.json
```
, DTCG-style)
Style Dictionary input JSON
Platform theme sources (Compose/Kotlin/TS) only when JSON source is unavailable

If source format is non-standard, explicitly state assumptions in dry-run output.

Required policies before writes

direction

:

code_to_figma

(default),

figma_to_code

,

bidirectional

```
deletePolicy
```
: default
```
archive_only
```
(NOT delete)

conflictPolicy

:

prefer_code

,

prefer_figma

,

manual_review

```
namingPolicy
```
: token key normalization strategy
```
modePolicy
```
: code mode <-> Figma mode mapping

Never delete by default. Deletion requires explicit user instruction.

Normalization rules

Normalize both sides to canonical rows:

```
key
```
(canonical token name)
```
type
```
(
```
COLOR
```
,
```
FLOAT
```
,
```
STRING
```
,
```
BOOLEAN
```
)
```
modeValues
```
(light/dark/etc.)
```
aliasTarget
```
```
scopes
```
```
codeSyntax
```

Name normalization examples:

```
color.bg.primary
```
<->
```
color/bg/primary
```
```
Neutral10
```
<->
```
Neutral/10
```
only if explicitly mapped by naming policy

Value validation (required)

Dry-run must validate values, not only presence/type.

COLOR: compare RGBA with tolerance
```
epsilon = 0.0001
```
FLOAT: strict numeric comparison unless tolerance is configured
STRING/BOOLEAN: strict equality
Aliases: compare canonical alias targets

Drift categories

Each drift item must include one of:

```
missing_in_figma
```
```
missing_in_code
```
```
value_mismatch
```
```
alias_mismatch
```
```
type_mismatch
```
```
mode_mismatch
```
```
scope_mismatch
```
```
code_syntax_mismatch
```
```
broken_alias
```

Dry-run output format

Always return:

Headline summary:

json

{
  "create": 0,
  "update": 0,
  "aliasFix": 0,
  "scopeFix": 0,
  "syntaxFix": 0,
  "archive": 0,
  "delete": 0
}

Detailed drift list with token keys and before/after values.

Then ask:

Dry-run complete. Apply these changes? (yes/no)

Report persistence (required)

Persist report JSON every run:

/tmp/sync-figma-token-dry-run-{runId}.json

/tmp/sync-figma-token-final-{runId}.json

If file persistence fails, mention that explicitly in output.

Conflict handling

When conflicting data is found (type/mode/alias ambiguity):

If
```
conflictPolicy=manual_review
```
, list conflicts and STOP.
If
```
conflictPolicy=prefer_code
```
, update Figma to source values/types.
If
```
conflictPolicy=prefer_figma
```
, keep Figma and emit drift as informational.

Apply order

Apply deltas in this order:

Ensure collections/modes
Create missing primitives
Create/update semantic aliases
Apply value updates
Apply scopes and code syntax
Archive stale tokens per
```
deletePolicy
```

Never parallelize write

use_figma

calls.

Success condition

After apply, run a fresh diff. Success = unresolved drift is zero, or only explicitly approved exceptions remain.

sync-figma-token

NPX Install

Tags

SKILL.md Content

sync-figma-token

Non-negotiable safety rule

Standard source formats (required)

Required policies before writes

Normalization rules

Value validation (required)

Drift categories

Dry-run output format

Report persistence (required)

Conflict handling

Apply order

Success condition