manage-variables-figma

manage-variables-figma — 变量 / 集合 / 模式 CRUD

对 Figma 变量系统进行增量、精细的修改：创建一个或多个变量、批量更新值、重命名、设置作用域和代码语法、添加或重命名模式，以及删除。所有操作都通过 use_figma 完成，适用于任何方案。

技能边界

• use_figma 规则——首先加载官方 figma-use 技能；它是完整的 Figma Plugin API 参考。这些脚本依赖的要点：使用带顶层 await 和 return 的纯 JS（不使用 IIFE 或 figma.closePlugin()；console.log 不会作为返回值返回），在每个脚本顶部用 const 内联输入，颜色值范围为 0–1，在任何文本操作前加载字体，使用 await figma.getNodeByIdAsync(...)，以及原子错误处理（脚本失败时不会应用任何操作——读取错误、修正并重试）。
• 从零开始搭建 → setup-design-tokens-figma。代码同步 → import-tokens-figma / export-tokens-figma。

工作流

1. 确定目标。 大多数操作都需要 ID。可从 export-tokens-figma 读取脚本或 get_variable_defs 获取 variableId/modeId/collectionId。也可以在脚本中按名称查找集合。
2. 选择操作，参阅 references/variable-ops.md——其中为每项操作提供了完整、可直接复制粘贴的 use_figma 代码片段：创建集合、创建变量、批量创建、批量更新、重命名、设置作用域、添加 / 重命名模式以及删除。
3. 通过 use_figma 运行（skillNames: "manage-variables-figma"）。批量更新大量值时，请使用 scripts/batch-update-variables.js（速度比逐个值单独调用快 10–50 倍）。
4. 确认。 每个代码片段都会返回受影响的 ID / 名称。使用 get_variable_defs 读取并验证。删除操作前，先向用户确认——删除集合会删除其中的所有变量，并解除任何对这些变量的引用。

关键规则

• 颜色值范围为 0–1。 输入十六进制颜色时使用 hexToRgb。
• 创建新变量时务必设置 scopes——默认的 ALL_SCOPES 会污染所有选择器。
• 设置代码语法（setVariableCodeSyntax('WEB', '--token-name')），使设计与代码中的命名保持一致。
• 重命名是安全的——会保留值和现有绑定。删除操作具有破坏性。
• 别名：使用 v.setValueForMode(modeId, figma.variables.createVariableAlias(targetVar)) 将一个变量绑定到另一个变量。