figma-manage-variables

figma-manage-variables — 变量 / 集合 / 模式的 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(...)，并遵循原子错误原则（脚本失败时不会应用任何更改——读取错误、修正后重试）。
• 从头开始引导 → figma-setup-design-tokens。代码同步 → figma-import-tokens / figma-export-tokens。

工作流

1. 确定目标。 大多数操作都需要 ID。通过 figma-export-tokens 读取脚本或 get_variable_defs 获取 variableId / modeId / collectionId。也可以在脚本中按名称查找集合。
2. 选择操作，查看 references/variable-ops.md — 其中为每项操作提供了完整且可直接复制粘贴的 use_figma 代码片段：创建集合、创建变量、批量创建、批量更新、重命名、设置作用域、添加 / 重命名模式，以及删除。
3. 通过 use_figma 运行（skillNames: "figma-manage-variables"）。批量更新大量值时，请使用 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)) 将一个变量绑定到另一个变量。