sync-figma-token

SKILL.md

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:

{
  "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.