sync-figma-token

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

该Skill用于实现令牌一致性工作流（代码令牌与Figma变量同步）。

强制前置条件：每次调用

use_figma

前必须先加载

figma-use

。

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.

生成dry-run输出后，必须停止操作并请求审批。

不得在生成dry-run输出的同一轮次中执行任何写入型
```
use_figma
```
调用。
提出常规确认问题（示例："是否应用这些更改？(是/否)"）。
仅在收到明确的肯定答复后才可继续操作。
若答复不明确或为否定，不得执行写入操作。

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.

优先按以下顺序使用真实令牌源：

设计令牌JSON（
```
tokens.json
```
、
```
tokens/*.json
```
，DTCG规范）
Style Dictionary输入JSON
仅当JSON源不可用时，才使用平台主题源（Compose/Kotlin/TS）

若源格式非标准，需在dry-run输出中明确说明假设前提。

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.

direction

：

code_to_figma

（默认）、

figma_to_code

、

bidirectional

```
deletePolicy
```
：默认
```
archive_only
```
（仅归档，不删除）

conflictPolicy

：

prefer_code

、

prefer_figma

、

manual_review

```
namingPolicy
```
：令牌键标准化策略
```
modePolicy
```
：代码模式与Figma模式的映射规则

默认禁止删除操作，删除需用户明确指令。

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

将两端数据标准化为规范条目：

```
key
```
（规范令牌名称）
```
type
```
（
```
COLOR
```
、
```
FLOAT
```
、
```
STRING
```
、
```
BOOLEAN
```
）
```
modeValues
```
（亮色/暗色等模式值）
```
aliasTarget
```
（别名目标）
```
scopes
```
（作用域）
```
codeSyntax
```
（代码语法）

名称标准化示例：

```
color.bg.primary
```
<->
```
color/bg/primary
```
```
Neutral10
```
<->
```
Neutral/10
```
（仅当命名策略明确映射时生效）

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

Dry-run必须验证值的准确性，而非仅检查存在性或类型。

颜色：对比RGBA值，容差为
```
epsilon = 0.0001
```
浮点数：除非配置了容差，否则严格数值对比
字符串/布尔值：严格相等对比
别名：对比规范别名目标

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
```

每个差异项必须归为以下类别之一：

```
missing_in_figma
```
（Figma中缺失）
```
missing_in_code
```
（代码中缺失）
```
value_mismatch
```
（值不匹配）
```
alias_mismatch
```
（别名不匹配）
```
type_mismatch
```
（类型不匹配）
```
mode_mismatch
```
（模式不匹配）
```
scope_mismatch
```
（作用域不匹配）
```
code_syntax_mismatch
```
（代码语法不匹配）
```
broken_alias
```
（别名失效）

Dry-run output format

Dry-run输出格式

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)

必须返回以下内容：

摘要信息：

json

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

包含令牌键及前后值的详细差异列表。

随后询问：

Dry-run完成。是否应用这些更改？(是/否)

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.

每次运行需持久化报告JSON：

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

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

若文件持久化失败，需在输出中明确提及。

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.

当发现冲突数据（类型/模式/别名不明确）时：

若
```
conflictPolicy=manual_review
```
，列出冲突并停止操作。
若
```
conflictPolicy=prefer_code
```
，更新Figma以匹配源值/类型。
若
```
conflictPolicy=prefer_figma
```
，保留Figma的值，并将差异作为信息输出。

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.

按以下顺序应用增量更改：

确保集合/模式存在
创建缺失的基础令牌
创建/更新语义别名
应用值更新
应用作用域与代码语法
根据
```
deletePolicy
```
归档过期令牌

不得并行执行写入型

use_figma

调用。

Success condition

成功条件

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

应用更改后，重新执行差异对比。成功 = 未解决的差异为零，或仅剩余明确批准的例外项。