cc-figma-tokens

cc-figma-tokens — Component Contracts 令牌技能

根据 component-contracts 令牌文件构建 Figma 变量集合。此技能会创建 Primitive 和 Semantic 变量集合，供所有组件绑定。

前置条件 — 请先加载以下技能：

• figma-use — 插件 API 语法规则（每次调用 use_figma 前都必须加载）
• figma-generate-library — 设计系统工作流和变量创建模式

在此技能中调用 use_figma 时，始终传入 skillNames: "cc-figma-tokens"。

---

1. 配置

首先，从项目根目录读取 .component-contracts。此文件包含所有必需的配置。任何响应中都不得输出 FIGMA_ACCESS_TOKEN。

FIGMA_ACCESS_TOKEN=...       # never output this value
FIGMA_FILE_KEY=...           # use for all use_figma calls
TOKENS_DIR=...               # root directory of token files
CONTRACTS_DIR=...            # root directory of contract files

如果缺少 .component-contracts，请告知用户复制 .component-contracts.example 并填写其值后再继续。

---

2. 令牌文件结构

Component-contracts 使用 W3C DTCG 令牌格式，并分为两个层级：

{TOKENS_DIR}/
  primitive/
    color.tokens.json
    motion.tokens.json
    shape.tokens.json
    space.tokens.json
    typography.tokens.json
  semantic/
    semantic.tokens.json

层级 1 — Primitives：原始值。使用带刻度后缀的名称（color/blue/500、space/4）。没有别名。单一模式：Value。

层级 2 — Semantic：指向 Primitives 的别名。使用角色命名（brand/500、surface/default、text/primary）。单一模式：Value。

在 Figma 中创建任何内容之前，请先读取所有令牌文件。先在内存中构建包含所有令牌及其值／别名的完整映射，再调用任何 use_figma。

---

3. Figma 变量架构

集合

严格按以下顺序创建两个集合：

集合	模式	用途
Primitives	Value	原始令牌值 — 绝不直接绑定到组件
Semantic	Value	指向 Primitives 的别名 — 组件绑定的就是这些

变量命名

使用 / 作为分组分隔符，与 W3C DTCG 路径结构一致：

Primitives:  color/blue/500, space/4, radius/md
Semantic:    brand/500, surface/default, text/primary, focus/default

变量作用域

绝不要使用 ALL_SCOPES。 根据令牌的语义角色分配作用域：

令牌角色	作用域
颜色 — 背景／填充	FRAME_FILL、SHAPE_FILL
颜色 — 文本	TEXT_FILL
颜色 — 边框／描边	STROKE_COLOR
颜色 — 焦点环	FRAME_FILL、SHAPE_FILL、STROKE_COLOR
间距 — 内边距、间隙	GAP
间距 — 边框宽度	STROKE_WIDTH
边框圆角	CORNER_RADIUS
排版 — 字号	FONT_SIZE
排版 — 字重	FONT_WEIGHT
排版 — 行高	LINE_HEIGHT
Primitives（全部）	[] — 在属性面板中隐藏

注意： HORIZONTAL_PADDING 和 VERTICAL_PADDING 不是 Figma 插件 API 中有效的 VariableScope 枚举值。所有间距变量仅使用 GAP。

代码语法

每个变量都必须设置 WEB 代码语法。使用 var() 包装器，并传入 CSS 自定义属性名称：

Primitive color/blue/500  →  var(--ds-color-blue-500)
Semantic brand/500        →  var(--ds-brand-500)
Semantic surface/default  →  var(--ds-surface-default)

CSS 命名约定：--ds-{path-with-dashes}，其中 / 替换为 -。

ANDROID 和 iOS 不使用 var() 包装器。

---

4. 执行模式

默认（快速）： 展示 Phase 0 计划并等待批准，然后依次运行 Phases 1–4，中途不停顿。所有运行默认采用此模式。

调试模式： 每个阶段结束后暂停，并等待明确批准后再继续。适用于排查问题或验证中间结果。提示词中包含“debug mode”即可启用。

---

5. 工作流

批处理要求（对性能至关重要）

每个集合只需调用一次 use_figma，即可创建所有变量。 切勿逐个或按类别创建变量。

• 一次 use_figma 调用即可创建 Primitives 集合及其中的所有变量
• 一次 use_figma 调用即可创建 Semantic 集合及其中的所有别名
• 不要在变量之间写入中间状态文件
• 不要在单个变量之间进行验证
• 整个集合创建完成后只验证一次

创建 Token 是确定且低风险的。figma-generate-library 中的状态记录表和中间文件写入模式不适用于此处——完全跳过。先读取所有 Token 文件，在内存中构建完整的变量映射，然后对每个集合执行一次调用。

如果某个集合超过约 80 个变量，必须拆成两次调用，则按类别拆分（例如：一次创建颜色，另一次创建其他所有变量）——切勿按单个变量拆分。

---

阶段 0 — 检查（只读）

创建任何内容之前：

1. 从 TOKENS_DIR 读取所有 Token 文件
2. 检查 Figma 文件——查看是否存在名为 Primitives 或 Semantic 的变量集合
3. 如果集合已存在，检查这是创建操作还是更新操作
4. 向用户展示摘要：各层级的 Token 数量、现有与新增的集合，以及任何冲突
5. 等待用户明确批准后再继续

阶段 1 — Primitives 集合

1. 读取所有原始 Token 文件，并在内存中构建完整的变量映射
2. 创建仅包含一个 Value 模式的 Primitives 集合
3. 在一次 use_figma 调用中创建所有原始变量——颜色、间距、动效、形状、排版
4. 为所有原始变量设置 [] 作用域（隐藏）
5. 为所有原始变量设置 WEB 代码语法
6. 验证：调用 get_metadata，确认变量数量与 Token 文件中的数量一致
7. 在调试模式下：继续前等待用户检查点

阶段 2 — Semantic 集合

1. 读取语义 Token 文件，并将所有 {token.path} 引用解析为 Primitive 变量 ID
2. 处理创建顺序——别名指向其他语义变量的变量（例如，border/brand → brand/500）必须在其目标变量之后创建
3. 创建仅包含一个 Value 模式的 Semantic 集合
4. 使用 figma.variables.createVariableAlias，在一次 use_figma 调用中创建所有语义变量
5. 根据语义角色设置作用域（参见 §3 作用域表）
6. 为所有语义变量设置 WEB 代码语法
7. 验证：调用 get_metadata，确认所有别名均能正确解析
8. 在调试模式下：继续前等待用户检查点

阶段 3 — 显式模式赋值

两个集合都创建完成后，对文件中的每个节点调用 setExplicitVariableModeForCollection，强制使用 Value 模式。这可以避免变量显示为未解析的幽灵模式问题。

// Apply to every node recursively
function applyModes(node, collection, modeId) {
  node.setExplicitVariableModeForCollection(collection, modeId);
  if ('children' in node) {
    for (const child of node.children) {
      applyModes(child, collection, modeId);
    }
  }
}

在调试模式下：继续前等待用户检查点

阶段 4 — 验证

运行最终验证：

• get_metadata — 确认两个集合均已创建，且变量数量正确
• get_screenshot — 直观确认变量在 Figma 中显示正常

返回结构化摘要：

{
  "collections": {
    "Primitives": { "variableCount": N, "modeCount": 1 },
    "Semantic": { "variableCount": N, "modeCount": 1 }
  },
  "status": "complete"
}

---

6. 更新与创建

如果变量集合已存在：

• 添加新变量：创建并添加别名，不要修改现有变量
• 更新值：修改 Primitive 的原始值，Semantic 别名链会自动更新
• 未经用户明确确认，绝不删除现有变量——组件可能已绑定这些变量
• 每次创建前进行幂等性检查：getLocalVariables().find(v => v.name === name && v.variableCollectionId === collId)

---

7. 已知限制

• 始终使用 setSharedPluginData / getSharedPluginData，切勿使用 setPluginData / getPluginData。非共享版本使用一个调试 UUID 作为插件标识符，该标识符会在每次工具执行时发生变化，导致存储的数据永久无法检索，并使文件膨胀。始终使用 component_contracts 命名空间：

  // CORRECT
  node.setSharedPluginData('component_contracts', 'dsb_key', value);
  node.getSharedPluginData('component_contracts', 'dsb_key');
  
  // WRONG — UUID changes per execution, data becomes orphaned
  node.setPluginData('dsb_key', value);
  

• 字间距不能存储为 Figma 变量——Figma FLOAT 变量是无单位整数；基于 em 的字间距值与之不兼容。字间距只能通过文本样式处理，不能使用变量。

• HORIZONTAL_PADDING 和 VERTICAL_PADDING 不是有效的 VariableScope 值——Plugin API 未将它们作为枚举成员提供。所有间距变量只能使用 GAP。

• 排版变量——字号和字重可以存储为 FLOAT 变量。字体系列必须使用 STRING 变量。

• 允许使用链式别名：Semantic/brand/500 → Primitive/color/blue/500。不要展平此链。

• 创建顺序对链式语义别名很重要——先创建被别名引用的变量。例如，先创建 brand/500，再创建将其设为别名的 border/brand。

• Ghost 模式：创建集合时，Figma 会自动创建一个空的 Ghost 模式。这是预期行为。始终调用显式模式分配（阶段 3）以抑制它。