Figma 变量创建指南从源 Token 数据到语义化变量体系的建模与落地基于 figma-use Skill 实践【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南聚焦于「如何在 Figma 中基于已有的设计系统源数据JSON、CSS、主题定义等创建变量Variables」这一核心任务。内容来源于本仓库 figma-use Skill 的 wwds-variables--creating.md 文档并结合 变量模型文档 与 可运行代码模式 展开。读完本文你将掌握创建变量前如何诊断源数据结构、何时使用语义化别名、如何预判模式Modes拆分、如何设定 Scope 与 Code Syntax以及用 Figma Plugin API 落地变量创建与绑定的完整实操路径。创建之前先理解源数据的真实状态创建 Figma 变量的第一步不是打开插件写代码而是先理解源数据的状态。文档原文强调When creating Figma variables, you need to start by understanding the state of the source data.这意味着你需要回答几个问题用户提供的数据是完整的设计 Token 定义还是一份零散的值清单数据中是否已经隐含了「原语primitive/ 语义semantic」两层结构是否存在多主题如品牌主题需要额外层级数据是按平台WEB / iOS / Android分发的还是单一声明如果用户只是要求「根据这些值创建变量」他们真正想要的往往是一个能体现结构的变量体系而不是机械地把每个值变成一个变量。是否采用语义化别名semantic aliasing指向原语primitive将完全取决于你拿到的源数据输入。代码输入JSON / CSS的处理原则贴合代码但要拥抱设计语境当输入是代码形态JSON、CSS 等时你的目标应是尽可能贴近现有代码模式reflect the existing patterns as closely as possible同时把设计语境当作与代码不同的独立面来对待。这一点在实践中具体化为两个决策命名大小写不必照搬代码。代码里可能是 camelCase 或 kebab-case但在 Figma 中你可以放心使用句子式sentence case或首字母大写capitalized case来提高可读性——因为 Code Syntax见下文可以承载真实的代码形式名字本身不需要牺牲可读性去模拟代码。尊重代码中的既有模式。如果 CSS 变量已经是--color-bg-default这类语义命名那么在 Figma 中也应保持语义化而不是退化成--color-blue-500这种纯原语命名。创建前必须识别的三件事别名结构、模式需求与层级在创建任何变量之前理解底层结构至关重要。文档列出了三个必须在动手前想清楚的点1. 隐含的别名Aliasing结构如果源数据中存在隐含的「原语 语义」两层结构你必须把它还原出来——先建原语再让语义变量别名指向原语。如果源数据是单层扁平结构就创建无别名的扁平变量。拿不准时向用户确认ask。这条「决策规则」Decision rule在 wwds-variables.md 中被完整定义为如果源数据有两层原语 语义先创建全部原语再创建别名指向它们的语义变量如果源数据是单层扁平结构就创建无别名的扁平变量不确定时提问。从 variable-patterns.md 的源码可以看出别名的实现形态——语义变量通过VARIABLE_ALIAS类型的值引用原语变量semanticVar.setValueForMode(modeId, { type: VARIABLE_ALIAS, id: primitiveVar.id });当原语变量变化时语义变量在所有模式Modes下都会自动同步更新。2. 预判模式Modes需求你可能需要提前预判 Modes以决定如何拆分变量集合。文档特别指出在复杂系统中尺寸Sizes和颜色Colors往往有不同的 Mode 需求。例如颜色需要 Light / Dark 模式而尺寸可能只有一套语言相关的字符串变量则可能要为每种语言建一个 Mode。因此创建结构时必须把 Mode 的差异纳入考虑。3. 是否需要扩展集合Extended Collections如果存在品牌化主题等场景可能需要基于一个集合创建扩展集合只覆盖其中一部分值——这类似于 CSS 中的继承与覆盖inheritance and overrides。复杂的企业级Enterprise方案下多集合 扩展集合的布局可能就是正确的最佳实践。最佳实践的相对性没有放之四海皆准的答案如果有人让你「基于最佳实践做决定」答案取决于环境的复杂程度一个简单的主题simple theme服务于简单需求就是最佳实践一个企业级计划的复杂扩展集合布局同样可能是最佳实践。关键在于不要脱离环境复杂度生搬硬套模板。这与 wwds.md 中「设计形态与实现形态是同一拼图的两块互补拼片」的理念一致设计的理想状态是便于实验、迭代与验证而实现的理想状态是严谨、高效。创建变量时你要在两者之间找到贴合当前环境的平衡点。变量模型基础创建前必须理解的六个概念在动手前还需要吃透 wwds-variables.md 中定义的变量模型。Figma 变量与代码库中的 Token 概念高度重叠但存在差距和 Figma 特有用法变量是单一值类型为 number、string、color、boolean。Collections集合与 Extended Collections扩展集合集合可以理解为 Figma 中的「组」。典型例子是名为 Colors 的集合内含 Light / Dark 两个 Mode每个值有两份定义。扩展集合则允许基于另一集合创建、仅覆盖部分值适用于品牌色主题等场景。Modes模式模式可以理解为明暗主题但用户可以为其定义任何维度——包括尺寸、语言Figma 中存在字符串变量。注意每个集合都至少有一个 Mode。Aliasing别名别名即让一个变量指向另一个变量。常见做法是让语义变量指向原语变量有些团队还会加入组件级 Token形成「原语 → 语义 → 组件」三层结构。Code Syntax代码语法Code Syntax 是 Figma 中用于代码库翻译上下文的面。你可以在任意变量上分别设置 WEB、iOS、ANDROID 三套代码语法当该变量在其他位置被引用Figma Dev Mode 视觉呈现、或通过 MCP 提供设计上下文时会以代码形式出现。它应被理解为「实例」级别的文档例如 CSS 场景写var(--the-thing)而不是--the-thing。Scope作用域variable.scopes: VariableScope[]指定该变量在 Figma 中可用于哪些属性。创建和使用变量时都重要。永远比不使用或设为ALL_SCOPES更好——越具体越好但并非所有集合都复杂到需要精确作用域。常用取值Scope 值用途ALL_SCOPES不受限制仅在不需要精确度时使用FILL_COLOR、STROKE_COLOR颜色绑定TEXT_CONTENT文本图层的字符串变量FONT_SIZE、FONT_WEIGHT、LINE_HEIGHT、LETTER_SPACING排版CORNER_RADIUS、WIDTH_HEIGHT、GAP布局 / 间距OPACITY图层不透明度Grouping分组命名变量名以斜杠/分隔每个斜杠代表一个在 Figma 中可视化呈现的组。做匹配时要注意代码前缀的一部分可能是集合名而非顶层分组有时代码中有 Figma 中没有的前缀这也 OK但不确定时要问。总可以通过 Code Syntax 校验已有变量。别忘了文本样式与效果样式系统可能会要求你同时处理 Token 库中的文本Text和效果Effect样式因为它们不在变量能力范围内阴影无法放进单个变量缺少复合 Token 类型。投影属于 效果样式Effect Styles但效果中的数值与颜色属性可以绑定到变量。字号阶梯type ramp必须用 文本样式Text Styles因为排版同样是复合属性无法放入单个变量但fontSize、fontFamily等单属性可以绑定变量。因此一个完整的 Token 库落地往往是「变量 文本样式 效果样式」三者的协同工作。创建变量的常见坑Gotchas创建阶段最容易踩的坑文档明确列出如下务必逐条对照createVariableCollection总是创建默认 Mode——集合创建后自带名为 Mode 1 的模式你需要重命名它或删除后新建而不是从零开始。重复的变量名静默通过——Figma 不会报错而是创建一个同名变量。创建前必须检查是否已存在。变量别名要求目标在同一文件内——Plugin API 不支持跨文件别名若要别名指向库变量必须先导入。setValueForMode设置别名要求精确形状——必须是{ type: VARIABLE_ALIAS, id: variableId }任何偏差都会静默写入错误值或直接抛错。落地实操用 Plugin API 创建变量可运行代码模式下面的代码来自 variable-patterns.md是 figma-use Skill 中可直接复用/改造的脚本模式。注意在使用use_figmaMCP 执行时应遵循 SKILL.md 的规则用return输出数据、代码自动包裹在异步上下文、颜色使用 0–1 范围。创建集合与模式const collection figma.variables.createVariableCollection(MyCollection); // 新集合默认带 1 个名为 Mode 1 的模式——务必重命名 collection.renameMode(collection.modes[0].modeId, Light); // 添加额外模式返回新的 modeId const darkModeId collection.addMode(Dark); const lightModeId collection.modes[0].modeId;Mode 数量上限与套餐相关Free 1 个Professional 最多 4 个Organization/Enterprise 40。若需要很多模式应拆分到多个集合——这与前面「尺寸与颜色可能有不同 Mode 需求」的判断相互印证。创建四种类型的变量figma.variables.createVariable(name, collection, resolvedType)的第二个参数接受集合对象或 ID 字符串推荐对象// COLOR —— 值使用 {r, g, b, a}全部 0–1 范围含 alpha const colorVar figma.variables.createVariable(my-color, collection, COLOR); colorVar.setValueForMode(modeId, { r: 0.2, g: 0.36, b: 0.96, a: 1 }); // FLOAT —— 用于间距、圆角、尺寸等数值 const floatVar figma.variables.createVariable(my-spacing, collection, FLOAT); floatVar.setValueForMode(modeId, 16); // STRING —— 用于字体族、字体样式名、任意文本值 const stringVar figma.variables.createVariable(my-font, collection, STRING); stringVar.setValueForMode(modeId, Inter); // BOOLEAN const boolVar figma.variables.createVariable(my-flag, collection, BOOLEAN); boolVar.setValueForMode(modeId, true);注意Paint 颜色用{r, g, b}无 alpha而 COLOR 变量值用{r, g, b, a}带 alpha不要混淆。创建后必须显式设置 ScopeSKILL.md 的第 16 条规则专门强调创建变量时永远显式设置variable.scopes默认的ALL_SCOPES会污染每一个属性选择器几乎从不是你想要的variable.scopes [FRAME_FILL, SHAPE_FILL]; // 仅填充选择器 variable.scopes [TEXT_FILL]; // 仅文本颜色选择器 variable.scopes [GAP]; // 仅间距选择器 variable.scopes [CORNER_RADIUS]; // 仅圆角选择器 variable.scopes []; // 从所有选择器中隐藏完整合法取值ALL_SCOPES、TEXT_CONTENT、CORNER_RADIUS、WIDTH_HEIGHT、GAP、ALL_FILLS、FRAME_FILL、SHAPE_FILL、TEXT_FILL、STROKE_COLOR、STROKE_FLOAT、EFFECT_FLOAT、EFFECT_COLOR、OPACITY、FONT_FAMILY、FONT_STYLE、FONT_WEIGHT、FONT_SIZE、LINE_HEIGHT、LETTER_SPACING、PARAGRAPH_SPACING、PARAGRAPH_INDENT。创建前始终检查文件已有的 Scope 模式匹配文件内既有的约定而不是强加新约定。设置 Code Syntaxvariable.setVariableCodeSyntax(WEB, var(--color-bg-default)); variable.setVariableCodeSyntax(ANDROID, colorBgDefault); variable.setVariableCodeSyntax(iOS, Color.bgDefault); // 读回variable.codeSyntax → { WEB: ..., ANDROID: ..., iOS: ... }从 Figma 名称推导 CSS 名称时斜杠和空格都要替换为连字符// 错误 —— CSS 变量名中残留空格 var(--${figmaName.replace(/\//g, -).toLowerCase()}) // 正确 —— 替换所有空白与斜杠 var(--${figmaName.replace(/[\s\/]/g, -).toLowerCase()}) // 最佳 —— 直接用源数据中的原始 CSS 变量名而非推导 var(${token.cssVar})创建前先发现已有变量关键习惯在创建新变量之前始终检查文件中的既有变量。不同文件使用不同的命名约定、Scope 模式和集合结构匹配已有内容// 列出集合及模式信息 (async () { try { const collections figma.variables.getLocalVariableCollections(); const results collections.map(c ({ name: c.name, id: c.id, varCount: c.variableIds.length, modes: c.modes.map(m ({ name: m.name, id: m.modeId })) })); figma.closePlugin(JSON.stringify(results)); } catch(e) { figma.closePluginWithFailure(e.toString()); } })()也可以构建 name→variable 查找表只为文件中没有匹配的 Token 创建新变量只创建差集 deltaconst varByName {}; for (const v of figma.variables.getLocalVariables()) { varByName[v.name] v; } // 按名称绑定到已有变量——无需 hex 值 function bindFill(node, varName) { const v varByName[varName]; if (!v) throw new Error(Variable not found: ${varName}); const paint figma.variables.setBoundVariableForPaint( { type: SOLID, color: { r: 0, g: 0, b: 0 } }, color, v ); node.fills [paint]; }对于需要异步 API 的场景可使用getLocalVariableCollectionsAsync()getVariableByIdAsync()获取包含 Code Syntax 与 Scope 的更丰富数据完整脚本见 variable-patterns.md 的listVariableCollectionsAndVariables函数。创建完成后的收尾绑定与模式应用创建变量通常是为了绑定到节点属性此处给出与「创建」直接衔接的关键绑定模式颜色绑定figma.variables.setBoundVariableForPaint(basePaint, color, colorVar)返回新的paint必须捕获返回值再赋给node.fills只有 SOLID paint 支持颜色变量绑定渐变/图片会抛错。数值绑定node.setBoundVariable(paddingTop, spacingVar)等可用于 padding、gapitemSpacing/counterAxisSpacing、圆角用topLeftRadius等四个单独角而非cornerRadius、尺寸width/height/minWidth/maxWidth、opacity、strokeWeight。fontSize、fontWeight、lineHeight不可通过setBoundVariable绑定需直接在文本节点上设置。模式应用frame.setExplicitVariableModeForCollection(collection.id, modeId)让该帧下所有绑定子节点解析到指定模式的值否则所有节点使用集合的默认第一个模式——这与「使用时注意 Mode 不匹配」的警告见 wwds-variables--using.md直接相关Figma 的默认模式未必是用户期望的模式。小结创建 Figma 变量不是机械的「值 → 变量」映射而是一次建模决策先诊断源数据识别两层结构原语 语义、隐含别名关系与 Mode 需求再规划结构集合、扩展集合、Mode、分组命名斜杠分隔与 Scope 的精确设定然后落地实现遵循「先发现已有变量、再创建差集」的习惯用 Plugin API 创建集合/变量、设置别名与 Code Syntax、显式声明 Scope并留意「默认 Mode 需重命名」「重复名静默通过」「别名跨文件不支持」等常见坑最后补齐短板阴影用效果样式、排版用文本样式二者均可与变量绑定共同构成完整的 Token 体系。如需继续深入可阅读同目录下的 使用变量指南、效果样式文档 与 文本样式文档或直接查阅 SKILL.md 获取完整执行规则。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考