组件命名规范的核心不是统一大小写，而是让设计师、产品经理和研发看到同一个名字时，能判断它是什么、属于哪里、有哪些可切换属性，以及代码里对应哪个对象。一套可执行的命名通常由“范围、对象、属性、取值”四部分组成；名称描述稳定身份，状态和尺寸放进属性，不把颜色、坐标或临时版本写进名字。
这篇文章只解决图层、组件、变体、状态和研发映射的命名问题。版本、复用边界和废弃流程由组件库治理方法承接，避免把所有治理规则塞进一张命名表。
先确定命名要解决的四个问题
- 能找到：按业务域、组件类型或属性搜索时，结果能够被稳定筛选。
- 能理解：新成员不打开画布，也能从名字判断对象用途和层级。
- 能复用：同一组件的尺寸、状态和变体通过属性切换，不复制出一串近义名称。
- 能映射：设计组件、文档条目和前端组件有明确对应关系，变更时能追到责任对象。
如果一个规则只让画布看起来整齐，却不能减少搜索、复用和交付中的歧义，它就只是格式偏好，不是命名规范。
建立固定语法：范围 / 对象 / 属性 = 取值
推荐把组件的稳定身份写在名称里，把可变化的维度写成属性。名称可以采用“业务域/类别/对象”的层级，例如 Commerce/Form/Button；属性则使用 Type=Primary、Size=Medium、State=Disabled。团队使用中文或英文都可以，关键是同一层只使用一种语言和同一顺序。
范围只在确实存在多产品、多端或多品牌时添加。一个只有单产品的团队若给每个组件都加产品前缀，会增加噪声；等到跨产品复用时，再补稳定且有辨识度的命名空间。
图层名和组件名不能共用一套颗粒度
组件名回答“这是什么可复用对象”，图层名回答“这个对象内部由什么组成”。按钮组件可以叫 Button，内部图层则使用 Container、Label、LeadingIcon。不要把内部图层也写成 Button-1、Button-2，否则研发无法区分结构角色。
- 页面：按业务任务或流程节点命名，例如
Order/Detail、Account/Security。 - 组件：按稳定对象与类别命名，例如
Form/Input、Navigation/Tabs。 - 内部图层：按结构角色命名，例如
Container、Label、HelperText。 - 实例：沿用组件名，不附加页面坐标；使用
Button，而不是Button-左上。
变体、状态和尺寸应写成属性
当多个版本共享结构，只是用途、尺寸或交互阶段不同，就把差异写成属性，不要复制成 蓝色按钮、大按钮、不可点按钮。推荐顺序是“用途 → 尺寸 → 状态 → 可选布尔项”，例如 Type=Primary, Size=Large, State=Loading, Icon=true。
状态属性只描述交互阶段，不承担业务文案。默认、悬停、聚焦、禁用、加载和错误等最小集合，需要按组件类型决定；具体取舍可由组件状态与变体清单继续检查。
变量命名描述语义，不描述当前外观
组件属性和设计变量要分开：前者描述“组件怎么变化”，后者描述“组件引用什么设计决定”。变量优先使用 text-primary、border-danger 这类语义名称，不用 dark-gray 或 red-2 代替业务含义。换主题后，语义不变、取值改变，名称才不会失真。
如果团队正在把颜色、字号和间距接入代码，先按Design Token 的分层方法建立基础值、语义和组件三层，再让组件只引用语义或组件层变量。
设计名称如何映射到前端组件
设计与代码不必强行使用完全相同的字符串，但必须维护一份唯一映射。设计侧的 Form/Input 可以对应代码中的 Input，属性 State=Error 对应 status="error"。映射表至少包含设计名称、代码对象、属性对应、负责人和状态。
出现一对多时先检查边界：如果一个设计组件需要映射三个结构完全不同的代码组件，它可能过于宽泛；如果三个设计组件都映射同一个代码组件，它们可能只是变体。跨 PRD、原型和代码继续维护同一对象时，可用三端一致性检查方法补齐变更记录。
五种常见错误及修正方式
- 按外观命名：
蓝色按钮改为Button / Type=Primary。 - 把状态塞进名称：
Button-禁用改为State=Disabled。 - 使用序号占位：
Card-3改为能说明任务的Content/ProductCard。 - 混用语言和分隔符：同一层级固定中文或英文，并统一使用斜杠分层。
- 把版本写进名字：
Input-v7-final应由版本记录管理，名称保持稳定。
组件文档至少记录七个字段
命名规则只有写进组件文档并用于评审，才会持续生效。每个组件至少记录：规范名称、用途、结构图层、属性与可选值、状态范围、设计—代码映射、负责人和变更记录。规则本身还要附“正确示例、错误示例、例外条件”，否则成员遇到新对象时仍会各自判断。
- 名称与路径：说明它属于哪个范围、类别和对象。
- 用途与边界：说明什么时候用，什么时候不该用。
- 结构图层：说明内部各层承担什么角色。
- 属性与状态：列出允许切换的维度和取值。
- 设计—代码映射：标明对应的代码组件与参数。
- 责任人与版本：记录谁维护、何时变更、替代项是什么。
在墨刀里把命名规则放进真实组件工作流
团队可以在墨刀设计中使用组件与变量管理重复元素和常用样式，再把命名路径、属性取值和负责人写进组件说明。新建或引入外部组件库时，先选一条真实业务链路做小范围整理：统一组件名，拆出状态与尺寸属性，绑定语义变量，再让研发核对映射；不要一开始就批量重命名整个资产库。
- 组件资源进入团队库前，先检查名称是否符合统一语法。
- 设计评审同时检查视觉结果和属性命名，避免错误继续复制。
- 准备搭建更完整的资产、变量和评审机制时，再进入设计系统搭建流程。
落地顺序：先整理一条业务链路
- 盘点：选登录、下单或审批等一条链路，导出其中使用的组件与图层名称。
- 归类：按页面、组件、内部图层、变量分组，标记重名、近义名和序号名。
- 定语法：确定层级顺序、属性顺序、语言与分隔符，制作十组正反例。
- 建立映射：让研发核对代码对象和属性，处理一对多或多对一。
- 试运行：在一个迭代中执行命名检查，记录搜索、复用和交付时仍出现的歧义。
- 再推广：规则稳定后批量整理其余资产，旧名称保留迁移与替代记录。
组件命名规范检查清单
- 名称能说明范围、类别和对象，不使用坐标、颜色、序号和“最终版”。
- 用途、尺寸、状态和布尔项使用属性表达，属性顺序固定。
- 图层名描述结构角色，组件名描述可复用对象，二者颗粒度不同。
- 变量名描述语义，不把当前颜色值写进语义层。
- 设计组件与代码对象存在唯一、可维护的映射和负责人。
- 规则包含正例、反例、例外和迁移方法，并进入日常评审。
常见问题
组件应该用中文还是英文命名？
两者都可以。若研发组件、变量和文档主要使用英文，英文更利于映射；若团队成员主要通过中文检索，中文也能成立。不要在同一层级无规则混用，并为必要的跨语言映射保留别名。
旧组件需要一次性全部重命名吗？
不需要。先整理高频组件和一条真实业务链路，建立“旧名 → 新名 → 替代项”清单；直接全量改名容易让历史文件、实例和代码映射同时断裂。
命名规范由设计师还是研发负责？
设计负责人维护对象语义和结构，研发负责人确认代码映射，产品或业务负责人补充场景边界。最终应有一个明确维护人，跨角色共同评审，但不能出现无人负责的共识文档。
总结
可执行的组件命名规范，要把稳定身份和可变属性分开：名称描述范围、类别与对象，属性描述用途、尺寸和状态，变量描述设计语义，映射表连接设计与代码。先用一条真实业务链路验证规则，再逐步推广，比一次性整理全库更容易保持组件、文档和研发实现一致。
信息核验日期：2026-09-28。墨刀相关表述依据当前官方界面设计页与已提供工作台素材；具体入口和界面以实际账号版本为准。
