figma-generate-library 命名规范全指南：从 Figma 变量到代码 Token 的完整映射体系

figma-generate-library 命名规范全指南：从 Figma 变量到代码 Token 的完整映射体系

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本文是 figma-generate-library skill 的命名约定参考文档的完整展开，系统覆盖变量、组件、页面、变体、样式、分隔页与状态指示的全部命名决策，并以仓库中的 helper 脚本 与 token-creation 参考 为源码证据，深入讲解 Figma 命名与代码 Token 名之间的双轨映射原理。读者读完将掌握一套可直接落地的设计系统命名体系，以及"何时匹配现有文件、何时使用默认约定"的决策方法。

1. 变量命名：斜杠层级是唯一通用模式

1.1 斜杠层级（Slash Hierarchy）

所有 Figma 变量都使用斜杠分隔的路径命名。斜杠在变量面板中创建可视化分组，并直接映射到代码中的 Token 层级结构：

{category}/{subcategory}/{role}

来自 Simple DS 与 Material 3 的真实示例：

color/bg/primary color/bg/secondary color/text/primary color/text/muted color/border/default color/border/focus color/feedback/error color/feedback/success spacing/xs spacing/sm spacing/md spacing/lg spacing/xl spacing/2xl radius/none radius/sm radius/md radius/lg radius/full typography/body/font-size typography/body/line-height typography/heading/font-size typography/heading/font-weight

这一约定在仓库的脚本实现中得到了硬编码级别的贯彻。查看 createSemanticTokens.js，其tokenMap参数的name字段明确要求"Variable name using slash hierarchy (e.g. "color/bg/primary")"，脚本通过figma.variables.createVariable(token.name, collection, token.type)按该名称原样创建变量，并在随后设置每个 mode 的值、作用域（scope）与三端代码语法（code syntax）。换句话说，斜杠层级不仅是命名习惯，更是脚本数据模型的输入契约。

1.2 Primitives 集合

原始（Primitive）变量持有原始值，不暴露给消费者（scope =[]，空作用域意味着从所有选择器中隐藏）。它们使用扁平的{family}/{step}格式，与 Simple DS 的色彩刻度约定一致：

blue/50 blue/100 blue/200 ... blue/900 gray/50 gray/100 ... gray/900 red/500 green/500

步进数字遵循目标代码库的约定：

• 代码库使用100–900→ 用100–900；
• 代码库使用50–950→ 用50–950；
• 无代码库约定 → 默认使用100–900，步进 100。

在源码层面，token-creation.md 给出了真实 SDS 数据的创建脚本：blue/500 = #3B82F6、gray/900 = #111827等，并强调原始变量必须设置v.scopes = []。唯一例外是半透明覆盖层原始色（如带 alpha 的 Black/White），它们获得["EFFECT_COLOR"]作用域，以便出现在阴影选择器中。

1.3 Semantic 集合

语义变量对原始变量做别名引用，使用基于角色的{category}/{role}或{category}/{subcategory}/{role}模式：

color/bg/primary → alias: primitives/white (light), primitives/gray/900 (dark) color/bg/secondary → alias: primitives/gray/100 (light), primitives/gray/800 (dark) color/text/primary → alias: primitives/gray/900 (light), primitives/white (dark) color/text/secondary → alias: primitives/gray/600 (light), primitives/gray/400 (dark) color/border/default → alias: primitives/gray/200 (light), primitives/gray/700 (dark)

铁律：语义变量绝不能持有原始 hex 值——它们必须始终别名引用原始变量。如果需要新颜色值，先创建原始变量，再创建语义别名。

createSemanticTokens.js 中正是这样实现的：每个 token 的values可以是原始值，也可以是{type: 'VARIABLE_ALIAS', id: variableId}别名对象；脚本对每个 mode 调用variable.setValueForMode(modeId, value)。而 token-creation.md 进一步展示了完整链路：figma.variables.createVariableAlias(getPrim(lightPrim))返回{type:'VARIABLE_ALIAS', id: variable.id}，并强调"被别名的变量必须与语义变量具有相同的resolvedType"以及"绝不在语义层重复原始值"。

1.4 大小写规则

默认：全部小写 + 正斜杠，如color/bg/primary、spacing/2xl。

何时可以偏离：

• 现有文件使用 PascalCase（如 Material 3 使用Schemes/Primary）→ 跟随它；
• 设计团队为变量面板可读性偏好 PascalCase → 可接受，前提是代码语法单独定义并使用平台正确的大小写；
• Mode 名称可以使用空格和混合大小写（如SDS Light、Mode 1 → Light）——它们是标签，不是标识符。

禁止：

• 变量名内使用 camelCase（colorBgPrimary作为 Figma 名称是错的，它只属于 Android 代码语法）；
• 路径段内使用空格：color/bg primary是错的，color/bg/primary才对。

关键区分：大小写规则适用于Figma 变量名。代码语法名遵循平台约定，与 Figma 名称的大小写无关——详见第 9 节。

1.5 发现阶段的命名映射（Phase 0）

在 Phase 0 发现阶段，必须显式捕获代码 Token 与 Figma 名称的双侧映射。这里给出一个完整的映射记录示例：

For each token found in the codebase: CSS variable: --sds-color-background-brand-default Figma name: color/bg/brand/default (slash hierarchy, no vendor prefix) WEB syntax: var(--sds-color-background-brand-default) (exact CSS name) ANDROID syntax: sdsColorBackgroundBrandDefault (camelCase) iOS syntax: Color.backgroundBrandDefault (dot-notation)

该映射存入 state ledger，在 Phase 1 调用setVariableCodeSyntax时使用。如果掌握原始 CSS 变量名，绝不要从 Figma 名称推导代码语法——始终使用原始名。discovery-phase.md 给出了 CSS → Figma 的翻译规则："在类别边界处将连字符替换为斜杠，保留路径最后一段内的连字符"：--color-bg-primary→color/bg/primary，而--color-bg-primary-hover→color/bg/primary-hover。

2. 组件命名：三层命名空间体系

2.1 主组件：PascalCase，无前缀

面向库消费者的已发布组件使用纯 PascalCase 名称：

Button Input Checkbox Toggle Avatar Badge Card Dialog Tooltip Banner

不要为公共组件添加命名空间前缀（如DS/Button或sds-Button）。组件名中的斜杠会在 Assets 面板中创建嵌套分组——这对子组件是正确的，但对顶层公共组件是错的。

2.2 子组件：下划线前缀 + 斜杠命名空间

不面向库消费者的内部子组件使用_前缀。这使它们默认从 Assets 面板隐藏，并提示其他设计师不应直接使用：

_Button/Slot (internal icon slot for Button) _Input/Indicator (internal state indicator for Input) _Badge/Dot (internal dot sub-component of Badge) _Parts/Avatar.Status (UI3 pattern: _Parts/{ParentName}.{SubPart}) _Slider/Handle (UI3 pattern: _{ParentName}/{SubPart})

模式规则：

• 所有内部子组件都用_前缀——没有例外；
• 使用斜杠命名空间将子组件归组到父组件下：_Button/IconSlot；
• 被多个父组件共享的子组件，使用_Parts/{ComponentName}.{SubPart}。

2.3 私有文档组件：.前缀

仅用于内部文档（不用于生产）的组件使用.前缀：

.ExampleCard .GuidelineHeader .DemoFrame

这使它们对消费者隐藏，同时保持在画布上可访问。

2.4 组件命名与脚本的一致性

createComponentWithVariants.js 以name参数创建组件集（如"Button"），并以Property=Value组合为每个变体命名，最后调用figma.combineAsVariants(components, page)生成组件集并componentSet.name = name。可见组件集名称（PascalCase）与变体名称（Size=Small, Style=Primary）由同一脚本统一生成，这正是第 4 节变体命名规范在实现层面的落地。

3. 页面命名：三种模式，择一而从

五个参考设计系统使用三种不同的页面命名模式。选择一种模式，并在文件的所有页面中保持一致。

3.1 模式 1：纯名称（Simple DS、Material 3、Polaris）

最常用的模式，干净、可读、无装饰：

Cover --- Foundations Icons --- Accordion Avatars Buttons Cards Dialog Inputs Menu --- Utilities Component Playground

从零开始，或目标文件已使用该风格时，使用此模式。

3.2 模式 2：Emoji 前缀 + 状态（UI3 Library）

最具表现力的模式。页面名称编码了资源类型、设计状态与代码就绪度。

解剖结构：[Asset Type Emoji] [Optional FPL Label] [Status Circle] Component Name [Code Status Bracket]

示例：

Overview Status Key --- FPL COMPONENTS (go/fpl) [C-flag] FPL [Green] Buttons [C-flag] FPL [Green] Inputs [C-flag] FPL [Yellow] Popovers [future] --- UI3 COMPONENTS [C-flag] [Green] Comments --- PATTERNS [P-flag] [Green] Editor / Layers --- [Book] Cover [Headstone] Deprecated

仅当构建大型、多团队设计系统且需要生命周期追踪时，或目标文件已使用该模式时，才使用它。

3.3 模式 3：Emoji 前缀（Shop Minis）

UI3 模式的轻量版本，不带状态圆点：

📔 Cover ℹ️ About 🚀 Getting started ——— THEME ——— Color Typography Spacing ——— COMPONENTS ——— Button Input Card

当目标文件已使用 emoji 前缀但不需要生命周期追踪时使用。

3.4 通用规则（所有模式）

• Cover 永远是第一页；
• 分隔页位于每个逻辑区块前后；
• 基础/Token 页永远排在组件页之前；
• 工具与内部页永远排在最后；
• 选择一个约定，不要在文件内混用模式。

页面结构在 SKILL.md 的 Phase 2 中被固化为固定骨架：Cover → Getting Started → Foundations → --- → Components → --- → Utilities。而 inspectFileStructure.js 会遍历figma.root.children返回所有页面及其子节点数量——命名任何页面之前，先用它确认现有页面的命名模式。

4. 变体命名：Property=Value 格式

4.1 Property=Value 格式

组件集中的所有变体属性及其值都使用Property=Value格式：

Size=Small, Style=Primary, State=Default Size=Medium, Style=Secondary, State=Hover Size=Large, Style=Ghost, State=Disabled

属性名在可能的情况下与代码 prop 名保持一致：

源码实现见 createComponentWithVariants.js：脚本对变体轴做笛卡尔积后，用axisNames.map((ax, i) => \${ax}=${combo[i]}`).join(', ')精确生成Property=Value, Property=Value` 形式的变体名称——命名规范与脚本逻辑一一对应。

4.2 属性值大小写

属性值在 Figma 中使用Title Case（便于在变体面板中阅读），映射到代码中的小写：

4.3 布尔属性

Figma 中的布尔组件属性使用true/false作为值（Figma 原生布尔），不使用Yes/No或On/Off。

discovery-phase.md 给出了代码 props → Figma 变体属性的完整映射范式：Union 类型 props → VARIANT 属性；字符串内容 props → TEXT 属性；布尔 props → BOOLEAN 属性（与交互状态组合时为 VARIANT State）；子节点/插槽 props → INSTANCE_SWAP 属性。例如ButtonProps的size: 'sm'|'md'|'lg'、variant: 'primary'|'secondary'、disabled?: boolean会生成3 sizes × 2 styles × 4 states = 24个变体。

5. 样式命名（文本样式与效果样式）

5.1 文本样式：category/name

Display/Large Display/Medium Display/Small Heading/1 Heading/2 Heading/3 Body/Large Body/Medium Body/Small Label/Large Label/Small Code/Inline

类别段映射到排版角色。尽可能使用与代码库排版刻度相同的类别名。这在 token-creation.md 的 Text Style 创建脚本中体现为ts.name = name（如Display/Hero、Heading/H1、Body/Large、Label/Small、Code/Base），并附带完整的字重、字号、行高、字距定义。

5.2 效果样式（阴影）：category/name

Shadow/None Shadow/Subtle Shadow/Medium Shadow/Strong Shadow/Overlay Elevation/0 Elevation/1 Elevation/2 Elevation/3 Elevation/4 Elevation/5

• Shadow/用于命名的语义阴影；
• Elevation/N用于 Material Design 风格的数字高程等级。

阴影无法成为 Figma 变量——它们只能成为Effect Styles。仓库脚本展示了 CSS 到 Figma 的转换：CSS 的0 4px 6px -1px rgba(0,0,0,0.1)转为{ type: "DROP_SHADOW", offset: {x:0, y:4}, radius: 6, spread: -1, color: {r:0,g:0,b:0,a:0.1} }，M3 风格的双阴影（umbra + penumbra）对应Elevation/1、Elevation/2、Elevation/3等。

6. 分隔页

分隔页是空页面，唯一目的是在 Figma 页面面板中制造视觉分隔。两种约定：

三条短横线约定（---）最常见，也是新文件的默认选择。除非目标文件使用装饰文本风格，否则用它。

分隔页放置位置：

Cover --- ← after cover Foundations Icons --- ← before components [component pages] --- ← before utilities Utilities

7. 状态指示器（UI3 Emoji 系统）

UI3 Library 在页面名中使用彩色圆形 emoji 来传达设计就绪度。该系统是可选的，但对大型团队非常有效。

代码就绪度通过附加在组件名后的方括号传达：

文档状态（组件页内）：

如果构建 UI3 风格系统，每个文档 frame 会获得一个状态横幅，使用以下标签之一：

• APPROVED— 已全面验证
• READY FOR REVIEW— 等待签核
• WORK IN PROGRESS— 正在积极设计
• NEEDS UPDATE— 已过时，需要修订
• DO NOT REFERENCE— 不应使用

该系统仅建议用于大型多团队系统——生命周期追踪能提供真实价值时。小型系统应跳过 emoji 状态指示器，使用纯页面名。

8. 何时匹配现有文件，何时使用默认约定

命名任何东西之前，始终先检查。创建任何页面或变量前，先运行get_metadata或inspectFileStructure发现现有约定。

仓库中的 inspectFileStructure.js 正是为此设计的只读发现函数：它返回全部页面（含子节点数）、全部本地变量集合（含 mode 名与变量名列表）、全部组件集（含变体数与所在页面）、全部文本样式与效果样式。它在 SKILL.md 的 Phase 0 中被规定为"always first"的强制性步骤——写操作开始之前，先了解文件里已有什么。

8.1 匹配现有文件，当：

• 文件已有命名模式一致的页面（emoji 前缀、分隔符风格、大小写）；
• 文件已有命名体系成熟的变量集合；
• 文件由设计团队创建，承载了有意为之的决策；
• 任何现有组件名使用特定模式（PascalCase、kebab-case、命名空间前缀）。

8.2 使用本文档默认约定，当：

• 从一个全新的、无任何内容的 Figma 文件开始；
• 现有约定不一致（风格混杂 = 没有约定可匹配）；
• 用户明确要求按照最佳实践构建全新设计系统。

8.3 当代码与 Figma 不一致时：

如果代码库使用button-primary，但 Figma 有一个名为Button的组件，不要重命名 Figma 组件。而是：

• 保留 Figma 名Button（PascalCase，人类可读）；
• 将变量代码语法设置为代码库中的精确 CSS Token 名；
• 将 Code Connect source 路径设置为实际代码文件，并使用精确的代码组件名。

规则：Figma 名称服务于设计师；代码语法与 Code Connect source 路径承载精确的代码标识符。这两个身份体系并行运作。

code-connect-setup.md 展示了 Code Connect 映射的实操：add_code_connect_map接收nodeId、source（如src/components/Button.tsx）、componentName（如Button）与框架label（如React），即"Figma 节点 ↔ 代码组件"的双轨映射正是这一机制，与命名双轨原则互相印证。

9. Figma 变量名 vs 代码名：全景图

这是最容易被误解的领域之一。Figma 名称与代码名称刻意遵循不同约定——它们服务于不同受众，存在于不同环境。

9.1 为什么它们不同

9.2 转换规则

Figma variable name Code syntax (WEB) ────────────────── ───────────────── color/bg/primary → var(--color-bg-primary) spacing/xs → var(--spacing-xs) radius/md → var(--radius-md) typography/body/font-size → var(--typography-body-font-size) Pattern: replace "/" with "-", wrap in var(--)

Figma variable name Code syntax (ANDROID) ────────────────── ───────────────────── color/bg/primary → colorBgPrimary spacing/xs → spacingXs radius/md → radiusMd Pattern: replace "/" with "", capitalize each word after first

Figma variable name Code syntax (iOS) ────────────────── ───────────────── color/bg/primary → Color.bgPrimary spacing/xs → Spacing.xs radius/md → Radius.md Pattern: first segment becomes class name, remainder becomes property (camelCase)

关键：WEB 代码语法必须使用var()包装器。Figma 期望完整的 CSS 函数语法——不仅仅是属性名。如果只设置--color-bg-primary（不带var()），Dev Mode 将显示原始 hex 值而非变量引用。始终设置var(--color-bg-primary)。token-creation.md 将这一点标记为 "CRITICAL"，并在批量设置脚本中以v.setVariableCodeSyntax('WEB', \var(--${cssName})`)的形式强制执行；ANDROID/iOS 则不带包装器（如colorBgPrimary、Color.bgPrimary`）。

9.3 五个参考文件的真实示例

Material 3 的关键观察：Figma 名称Schemes/Primary使用带空格的 PascalCase，但 WEB 代码语法是var(--md-sys-color-primary)——完全 kebab-case 且带供应商前缀md-sys-。Figma 名称与代码语法几乎毫无相似之处。这在成熟设计系统中是有意为之且普遍的做法。

9.4 Figma 中的大小写：小写是默认，PascalCase 可用于展示

小写准则只是默认，并非普遍规则。真实文件的证据：

规则：当 Figma 名称将直接映射到 CSS 名称时用小写；当设计系统拥有与技术代码名不同的人类可读变量名时，用 PascalCase（或匹配现有文件）。

9.5 当代码库不使用 CSS 自定义属性时

某些 JavaScript 优先的系统（Chakra、Ant Design、MUI）根本不使用 CSSvar(--...)。它们的 Token 存在于 JS theme 对象中：

Chakra: colors.gray[500] → JS: theme.colors.gray[500] Ant: colorPrimary → JS: token.colorPrimary MUI: palette.primary.main → JS: theme.palette.primary.main

这些情况下，将 WEB 代码语法设置为 JS 属性路径而非 CSS 变量：

// For a JS-object-based system like Chakra: v.setVariableCodeSyntax('WEB', 'colors.gray.500'); // For Ant Design: v.setVariableCodeSyntax('WEB', 'colorPrimary');

9.6 层级深度：匹配代码库

斜杠层数应镜像代码库的嵌套深度：

重要：供应商前缀（--p-、--md-sys-、--cds-）属于代码语法，不属于 Figma 变量名。color/bg/surface+var(--p-color-bg-surface)才是正确组合。

代码语法的优先级（来自 code-connect-setup.md 的推导规则）：

1. 最佳：使用代码库中的精确 Token 名（搜索--CSS 自定义属性、Swift 颜色扩展或 Kotlin theme 引用，使用那些精确字符串）；
2. 良好：从 Figma 变量名按一致规则推导：/和空格 →-，前缀var(--、后缀)；
3. 避免：猜测或发明代码库中不存在的名称。

且转换必须统一：一个集合内如果某个变量用了var(--color-bg-primary)，所有变量都应遵循相同的var(--{path-with-hyphens})模式。

10. 命名审计：把规范变成可验证的产出

命名规范最终要落到 QA。仓库为此提供了两个直接工具：

• validateCreation.js：验证创建的节点与预期数量、名称、结构一致，是 SKILL.md Phase 3/4 中"validate before proceeding"的执行者；
• inspectFileStructure.js：在 Phase 0 发现与 Phase 4 最终审计两个时点都可运行，返回的variableNames、componentSets列表可直接用于检查是否有重复名、未命名节点与不一致的大小写。

在 SKILL.md 的 Phase 4 中，命名审计（"no duplicates, no unnamed nodes, consistent casing"）是集成与 QA 阶段的硬性退出标准之一——它与本文档的命名体系共同构成了从"起名"到"验收"的完整闭环。

总结

命名不是风格偏好，而是一套需要与代码库对齐的工程契约。本文档的全部规则可以浓缩为三条决策主线：

1. 变量走斜杠层级：Primitive 扁平（blue/500）、Semantic 按角色（color/bg/primary）且必须别名引用原始值，scope 与 code syntax 必须全部设置；
2. 组件分三层命名空间：公共组件 PascalCase 无前缀、内部子组件_前缀 + 斜杠归组、私有文档组件.前缀；
3. Figma 名与代码名双轨并行：Figma 名称服务于设计师（可读、斜杠、小写或 PascalCase），代码语法承载精确标识符（var(--...)、camelCase、dot-notation），发现阶段记录映射、冲突时询问用户、以代码为值的事实来源。

这三点贯穿 figma-generate-library skill 的全流程，并被 scripts 中的可复用脚本固化为可重复执行的实现，最终在 Phase 4 的命名审计中接受验证。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills