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——它们是标签不是标识符。禁止变量名内使用 camelCasecolorBgPrimary作为 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并以PropertyValue组合为每个变体命名最后调用figma.combineAsVariants(components, page)生成组件集并componentSet.name name。可见组件集名称PascalCase与变体名称SizeSmall, StylePrimary由同一脚本统一生成这正是第 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 模式 2Emoji 前缀 状态UI3 Library最具表现力的模式。页面名称编码了资源类型、设计状态与代码就绪度。解剖结构[Asset Type Emoji] [Optional FPL Label] [Status Circle] Component Name [Code Status Bracket]段取值资源类型组件页使用 C-flag emoji模式页使用 P-flag emoji设计状态绿圈 Ready黄圈 WIP红圈 Do not use代码状态无 代码中已就绪[beta] Beta[future] 尚未构建示例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 模式 3Emoji 前缀Shop MinisUI3 模式的轻量版本不带状态圆点 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. 变体命名PropertyValue 格式4.1 PropertyValue 格式组件集中的所有变体属性及其值都使用PropertyValue格式SizeSmall, StylePrimary, StateDefault SizeMedium, StyleSecondary, StateHover SizeLarge, StyleGhost, StateDisabled属性名在可能的情况下与代码 prop 名保持一致Figma 属性代码 Prop 等价SizesizeStyle/VariantvariantState通常由 CSS 的:hover、:focus、:disabled控制但某些系统使用stateTypetypeDisableddisabled布尔值Iconicon布尔值或实例替换源码实现见 createComponentWithVariants.js脚本对变体轴做笛卡尔积后用axisNames.map((ax, i) \${ax}${combo[i]}).join(, )精确生成PropertyValue, PropertyValue 形式的变体名称——命名规范与脚本逻辑一一对应。4.2 属性值大小写属性值在 Figma 中使用Title Case便于在变体面板中阅读映射到代码中的小写Figma 值代码值Smallsmall/smMediummedium/mdLargelarge/lgPrimaryprimaryDisableddisabled布尔 propDefault通常是缺失/未设置的情况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/nameDisplay/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/nameShadow/None Shadow/Subtle Shadow/Medium Shadow/Strong Shadow/Overlay Elevation/0 Elevation/1 Elevation/2 Elevation/3 Elevation/4 Elevation/5Shadow/用于命名的语义阴影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 页面面板中制造视觉分隔。两种约定约定示例使用方三条短横线---Simple DS、UI3、Polaris、Material 3装饰文本——— COMPONENTS ———Shop Minis三条短横线约定---最常见也是新文件的默认选择。除非目标文件使用装饰文本风格否则用它。分隔页放置位置Cover --- ← after cover Foundations Icons --- ← before components [component pages] --- ← before utilities Utilities7. 状态指示器UI3 Emoji 系统UI3 Library 在页面名中使用彩色圆形 emoji 来传达设计就绪度。该系统是可选的但对大型团队非常有效。Emoji含义使用时机绿圈Ready / 已批准设计稳定、已评审、可安全使用黄圈WIP / 进行中设计正在积极修改可能变化红圈不可使用未就绪不要引用可能已弃用代码就绪度通过附加在组件名后的方括号传达方括号含义无组件已在代码中实现且稳定[beta]组件已在代码中但尚未稳定距就绪约 3 周[future]代码中尚未实现文档状态组件页内如果构建 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 名ButtonPascalCase人类可读将变量代码语法设置为代码库中的精确 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 为什么它们不同Figma 变量名代码语法WEB受众变量面板中的设计师CSS/Swift/Kotlin 开发者分隔符/斜杠— 在 Figma UI 中创建视觉分组-连字符— CSS 自定义属性语法要求大小写小写或为展示用 PascalCase见下文CSS 用 kebab-caseJS/Android 用 camelCase深度2–4 层CSS 为扁平JS 为点号表示命名空间隐式按集合显式前缀--p-、--md-、--cds-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 firstFigma 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 五个参考文件的真实示例文件Figma 变量名WEB 代码语法ANDROID 代码语法Simple DScolor/bg/primaryvar(--color-bg-primary)colorBgPrimarySimple DSspacing/smvar(--spacing-sm)spacingSmMaterial 3Schemes/Primaryvar(--md-sys-color-primary)colorPrimaryMaterial 3Corner/Extra-smallvar(--md-sys-shape-corner-extra-small)shapeCornerExtraSmallPolariscolor/bg/surfacevar(--p-color-bg-surface)—Material 3 的关键观察Figma 名称Schemes/Primary使用带空格的 PascalCase但 WEB 代码语法是var(--md-sys-color-primary)——完全 kebab-case 且带供应商前缀md-sys-。Figma 名称与代码语法几乎毫无相似之处。这在成熟设计系统中是有意为之且普遍的做法。9.4 Figma 中的大小写小写是默认PascalCase 可用于展示小写准则只是默认并非普遍规则。真实文件的证据文件Figma 大小写代码输出大小写原因Simple DScolor/bg/primary小写var(--color-bg-primary)直接映射——简单Material 3Schemes/PrimaryPascalCasevar(--md-sys-color-primary)PascalCase 在变量面板中更易读代码名独立定义Polariscolor/bg/surface小写var(--p-color-bg-surface)带供应商前缀的直接映射规则当 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 层级深度匹配代码库斜杠层数应镜像代码库的嵌套深度代码库模式Figma 深度示例--primary扁平1–2 层color/primary--color-bg-surface3 段3 层color/bg/surface--md-sys-color-primary供应商 3 段3 层供应商前缀只进代码语法color/primarytheme.palette.primary.main4 段3–4 层color/palette/primary/main重要供应商前缀--p-、--md-sys-、--cds-属于代码语法不属于 Figma 变量名。color/bg/surfacevar(--p-color-bg-surface)才是正确组合。代码语法的优先级来自 code-connect-setup.md 的推导规则最佳使用代码库中的精确 Token 名搜索--CSS 自定义属性、Swift 颜色扩展或 Kotlin theme 引用使用那些精确字符串良好从 Figma 变量名按一致规则推导/和空格 →-前缀var(--、后缀)避免猜测或发明代码库中不存在的名称。且转换必须统一一个集合内如果某个变量用了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 阶段的硬性退出标准之一——它与本文档的命名体系共同构成了从起名到验收的完整闭环。总结命名不是风格偏好而是一套需要与代码库对齐的工程契约。本文档的全部规则可以浓缩为三条决策主线变量走斜杠层级Primitive 扁平blue/500、Semantic 按角色color/bg/primary且必须别名引用原始值scope 与 code syntax 必须全部设置组件分三层命名空间公共组件 PascalCase 无前缀、内部子组件_前缀 斜杠归组、私有文档组件.前缀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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考