sync-figma-token

sync-figma-token

将此技能用于令牌对齐工作流（代码令牌与 Figma 变量）。

强制前置条件：每次调用 use_figma 前都必须先加载 figma-use。

不可妥协的安全规则

生成试运行输出后，必须停止并请求批准。

• 不要在生成试运行输出的同一轮中调用任何写入类 use_figma。
• 提出普通的确认问题（例如：“应用这些更改？（是/否）”）。
• 仅在收到明确肯定的批准后继续。
• 如果回复不明确或是否定的，不要执行写入。

标准源格式（必需）

优先使用真实的令牌源，并按以下顺序选择：

1. Design Tokens JSON（tokens.json、tokens/*.json、DTCG 风格）
2. Style Dictionary 输入 JSON
3. 仅当 JSON 源不可用时，才使用平台主题源（Compose/Kotlin/TS）

如果源格式不是标准格式，必须在试运行输出中明确说明所做的假设。

写入前必需的策略

• direction：code_to_figma（默认）、figma_to_code、bidirectional
• deletePolicy：默认为 archive_only（不是删除）
• conflictPolicy：prefer_code、prefer_figma、manual_review
• namingPolicy：令牌键规范化策略
• modePolicy：代码模式与 Figma 模式的映射

默认情况下绝不删除。删除必须得到用户的明确指示。

规范化规则

将两侧都规范化为以下规范行：

• key（规范令牌名称）
• type（COLOR、FLOAT、STRING、BOOLEAN）
• modeValues（light/dark 等）
• aliasTarget
• scopes
• codeSyntax

名称规范化示例：

• color.bg.primary <-> color/bg/primary
• 仅当 namingPolicy 明确映射时，Neutral10 <-> Neutral/10

值验证（必需）

试运行必须验证值，而不仅是是否存在或类型是否匹配。

• COLOR：比较 RGBA，容差为 epsilon = 0.0001
• FLOAT：严格比较数值，除非已配置容差
• STRING/BOOLEAN：严格相等
• 别名：比较规范别名目标

漂移类别

每个漂移项都必须包含以下其中一项：

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

试运行输出格式

始终返回：

1. 摘要标题：

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

2. 详细漂移列表，包含令牌键和更改前/后的值。

然后询问：

试运行已完成。应用这些更改？（是/否）

报告持久化（必需）

每次运行都必须持久化报告 JSON：

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

如果文件持久化失败，必须在输出中明确说明。

冲突处理

发现冲突数据（类型/模式/别名存在歧义）时：

• 如果 conflictPolicy=manual_review，列出冲突并停止。
• 如果 conflictPolicy=prefer_code，将 Figma 更新为源值/类型。
• 如果 conflictPolicy=prefer_figma，保留 Figma，并将漂移作为信息提示输出。

应用顺序

按以下顺序应用差异：

1. 确保集合/模式存在
2. 创建缺失的基础令牌
3. 创建/更新语义别名
4. 应用值更新
5. 应用作用域和代码语法
6. 根据 deletePolicy 归档过期令牌

绝不要并行调用写入类 use_figma。

成功条件

应用后，重新执行一次差异检查。 成功 = 未解决的漂移为零，或仅剩已明确批准的例外。