naming-audit

命名审计

一项用于审计设计系统组件和文档化模式命名规范的技能。生成违规报告，其中包含具体示例、歧义标记，以及附带理由的重命名建议。Token 名称由 token-audit 审计，prop 名称由 component-api-validator 审计，Figma 变量名称由 figma-variable-audit 审计；本技能会引用它们的审计结果，而不会重复审计。

开始之前：验证引用

确认此技能 frontmatter 中 references: 列出的每个路径都相对于此 SKILL.md 存在。如果有任何路径缺失，请停止：安装不完整，通常是因为扁平化安装程序（例如 npx skills install）遗漏了仓库根目录的 knowledge-notes/ 目录。告知用户通过 1-INSTALL.md 中的方法重新安装，并从安装根目录运行 verify-install.sh。只有用户明确要求继续时，才可在缺少引用的情况下继续；此时要在输出中说明内容是在未使用该套件参考资料的情况下生成的。

背景

命名是设计系统与使用者之间的主要接口。名称是设计师或开发者了解组件用途、Token 含义或模式行为时获得的第一条信息。好的名称具有可预测性：使用者在查阅前就能猜出名称所指的内容。糟糕的名称需要查阅、澄清，有时还得通过交流确认原意。

命名问题会不断累积。一个含义模糊的组件名称只会带来不便。但如果一个库中有二十个含义模糊的名称，有些遵循一种约定，另一些则遵循其他三种约定，那么新团队成员将无从入手，经验丰富的团队成员也无法信任这个系统。

本次审计涵盖组件和所有文档化模式的命名。它不会强制采用特定的命名规范，而是评估命名是否一致、明确且适合用途。

步骤 0：确定审计对象

审计名称之前，先确定这是哪种类型的共享 UI。库的类型会影响一致性要求的严格程度，以及建议是否恰当。

根据代码库特征分类：

• 设计系统 — 适用完整审计。命名规范应有文档记录、保持一致并得到执行。建议为任何未记录的约定创建决策记录。
• 组件库 — 命名一致性很重要，但应将“创建决策记录”的建议调整为“记录现有约定，即使只是在 README 中添加一条注释”。包含 5 个组件的库不需要正式的治理文档。
• 模式库 — 命名规范通常遵循文档工具的约定（例如 Fractal 的文件夹编号、Storybook 的故事层级）。除了内部一致性，还要依据工具的约定进行审计。模式名称通常描述模式展示的内容，而非它的作用——只有在这会造成混淆时才标记，不要一概视为违规。
• 工具集合 — 命名是主要接口。每个工具名称都必须明确且可预测，因为没有文档站点可供查阅。审计应严格要求清晰易懂，但不必过分苛求正式约定——即使 u-cw 符合前缀约定，clamp-width 也比它更好。

在报告标题中注明分类，格式为“库类型：[设计系统 / 组件库 / 模式库 / 工具集合]”，并据此调整建议的权重。

---

步骤 1：收集名称清单

在提问前，先从源中提取名称：

• 组件名称——公开的 barrel 导出（包根目录中的 index.ts / index.js，或 monorepo 中各个包的入口点）。导出项才是使用者实际会输入的名称；内部文件不算。如果没有 barrel 导出，则改为查看组件目录。记录每个导出的文件和行号，作为发现项的证据
• 模式名称——文档网站或 Storybook 层级（如果有相关文档）
• 现有的命名规范文档——README、CONTRIBUTING、ADR
• 相邻的报告——如果已运行过 token-audit 报告（令牌命名发现）或 component-api-validator 报告（属性命名），请在摘要中引用其 ID，而不要重复审计

只有在无法访问源时，才向用户索要名称列表，并说明名称分别来自何处。如果找不到 barrel 导出、组件目录或文档层级，请停止并询问组件位于何处，而不是审计文件名。

如果存在命名规范文档，请据此评估。如果不存在，则从现有名称中推导隐含规范，并指出它们彼此不一致之处。

小型系统说明（少于 5 个组件）： 对于这种规模的系统，命名审计更像是一场命名研讨会，而非合规审计。一致性检查（步骤 2）会很简单——只有 1–4 个组件时，要么所有名称都遵循同一规范，要么不一致之处一目了然。审计应重点关注名称能否清楚表达用途，以及是否存在歧义。趁系统规模还小、无需承担迁移成本时，提议现在将规范记录为决策记录（decision-record）。

步骤 1b：推导主导规范

如果没有命名规范文档，不要先停下来制定规范。请根据清单推导主导规范——即大多数名称遵循的模式——并在报告的规范清单中列出，以便团队确认或修正：

• 组件： 大小写形式、具体性顺序（ButtonPrimary 与 PrimaryButton）、缩写用法、前缀／后缀规则
• 模式： 名称描述用户任务（Sign in、Filter a list），还是涉及的组件（Form with validation），以及是否遵循文档工具的层级结构

根据推导出的规范进行审计，并说明该规范是推导得出的。如果没有占主导地位的规范，请将此作为发现项报告，而不是擅自选定一种规范。最后，提议使用 decision-record 技能将规范记录为决策记录。

步骤 2：评估组件命名

一致性检查

组件名称是否遵循一致的规范？请指出使用了哪些规范：

• 大小写形式：PascalCase、camelCase、kebab-case 或混用
• 具体性模式：从通用到具体（ButtonPrimary）或类别优先（NavigationPrimary）
• 缩写规则：是否使用缩写，以及缩写是否一致（Btn 与 Button、Nav 与 Navigation）

列出不符合库中其余名称所遵循模式的组件——下次修改时值得统一。如果差异可能是有意的命名决策，请说明这一点并询问，而不是直接假定这是疏漏。

目的清晰度检查

组件名称应能清楚表达组件的用途，无需依赖上下文。

标记以下名称：

• 对组件的具体用途来说过于笼统、毫无意义的名称：用于承担特定职责的组件上的 Wrapper、Base、Thing、Item。布局原语不在此列——Box、Stack、Flex、Grid、Container 和 Layout 都是广为认可的通用布局组件名称
• 描述视觉样式而非功能的名称：BlueCard、LargeText、RoundedButton
• 使用团队内部术语的名称：组织新人难以理解的名称
• 在相似组件之间含义模糊的名称：同一系统中的 Modal 和 Dialog，或没有明确区分的 Tooltip 和 Popover

对每个标记的名称：说明其含义为何模糊，并建议重命名。重命名建议应遵循系统既有的命名约定，并切实改进名称，而不只是换个名字。

后缀和前缀约定

如果系统使用后缀或前缀来表示类别、变体或角色，这些形式是否始终如一？

需要检查的常见模式：

• 尺寸后缀：ButtonSm、ButtonMd、ButtonLg——各组件的尺寸命名是否一致？
• 状态后缀：-active、-disabled、-loading——各组件的状态名称是否一致？
• 类别前缀：Form-、Nav-、Data-——所有相关组件是否都使用了前缀？

标记任何按照系统约定应使用前缀或后缀、但实际未使用的组件。

第 3 步：评估模式命名

仅当系统记录了模式时才执行（例如文档站点中的某个部分、Storybook 中的 “Patterns” 层级或 patterns/ 文件夹）。否则跳过并说明原因。

• 任务还是组合——模式名称应说明用户在做什么（Confirm a destructive action），而不是列出组成部分（Modal with two buttons）。仅当两个模式的名称无法区分时，才标记组合式名称
• 与文档工具的一致性——Storybook 层级和 Fractal 文件夹编号会规定顺序；标记归档位置不符合顺序的模式
• 与组件重名——模式与组件同名（模式 Wizard，组件 Wizard）会让搜索和 Figma 使用者感到困惑；标记并建议重命名其中一个

与其他审计结果交叉核对

Token 命名由 token-audit 负责，属性命名由 component-api-validator 负责。如果这两份报告中有任何一份存在，请在摘要中引用其命名问题的数量和 ID，让读者在一处了解整体命名情况。如果两份报告都不存在，而用户要求检查“所有命名”，请说明本报告未涵盖哪些部分，并提出可以执行这些审计。

第 4 步：生成命名审计报告

以一句标题式陈述开篇。例如：“组件命名一致，但 Token 命名存在三种相互竞争的约定——以下是造成摩擦的地方。”

---

命名审计报告

日期： [日期] 涵盖范围： [组件 / 模式 / 两者]，以及 [引用的 token-audit / component-api-validator 问题，或“未运行”] 约定文档： [存在并作为参考 / 不存在——根据清单推导约定]

---

摘要

一段话。整体命名质量如何？不一致是集中在某个阶段的系统、某个团队的贡献，还是分布广泛？最重要的发现是什么？直截了当地说明——如果命名一团糟，就明说。

---

约定清单

当前使用了哪些命名约定？列出主要约定以及发现的任何偏离约定的做法。本节旨在让团队了解当前的实际做法，为任何改进奠定基准。

---

调查结果

组件命名违规

ID	组件名称	证据	问题	重命名建议	严重程度
NA-01	[name]	[export file:line]	[specific issue]	[suggested name]	🔴/🟠/🟡/⚪

模式命名违规（如有记录模式）

ID	模式名称	证据	问题	重命名建议	严重程度
NA-[n]	[name]	[docs path or story id]	[specific issue]	[suggested name]	🔴/🟠/🟡/⚪

严重程度标准：

• 🔴 严重 — 名称会造成误导：它描述的并非该组件的功能，或两个导出的组件同名
• 🟠 高 — 歧义会带来实际的误用风险（使用者无法通过名称区分两个组件）
• 🟡 中 — 与主流约定不一致，但不会造成误导
• ⚪ 低 — 大小写或缩写不一致，不影响理解

---

建议

如果没有约定文档： 与团队确认推导出的约定，并在更改名称前将其记录下来。没有约定文档，重命名决策就没有稳定的参考依据，同样的不一致还会不断累积。

重命名顺序： 重命名组件和令牌属于破坏性更改。建议：

1. 优先修正新增项 — 今后遵循正确的约定
2. 按严重程度依次重命名：先处理高优先级违规，再处理中、低优先级违规
3. 组件重命名应采用弃用流程 — 应将旧名称标记为弃用并提供迁移路径，而不是立即移除
4. 将重命名作为破坏性更改发布公告 — 参见 change-communication skill

与决策记录的关联： 可提出使用 decision-record skill，将新推导出的约定或变更后的约定记录为决策记录。这是使用者最常查阅的治理决策，因此值得记录；但是否采纳由用户决定。

---

范围

• 已检查： [实际读取的 barrel 导出和文档来源；引用的相邻报告]
• 未检查： [无法检查的内容，例如 Figma 图层名称、仅供内部使用的组件]
• 如何确认“未发现”问题： [对于任何“无违规”声明，说明如何验证检查有效 — 如果报告未声称不存在问题，则省略]
• 假设： [例如，推导出的约定就是预期采用的约定]

报告结尾应附上以下说明。

---

结语（每份报告都必须包含）

报告结尾应写：

关于上下文的说明： 本次审计依据常见约定检查命名模式，但不了解名称的选用原因。有些不一致可能是有意区分。如果某项发现标记了团队有意采用的命名方式，请告知我 — 我会了解你们的约定，并在今后的运行中跳过这些模式。我们的目标是发现无意造成的不一致，而不是推翻有意作出的决定。

---

质量检查

• 每项违规都有证据（导出文件及行号，或文档路径），并附有具体的重命名建议及理由，而不只是标记问题
• 令牌和 prop 命名应引用其所属 skill 中的内容，不在此处重新审计
• 重命名建议遵循系统既有约定 — 在保持一致性的同时改进命名
• 约定清单部分描述系统的实际做法，而不是应该采用的做法
• 严重程度评级应反映实际影响：误导性名称优先级高，大小写不一致等轻微问题优先级低
• 建议部分应说明处理顺序 — 命名更改属于破坏性更改，应据此处理
• 必须包含范围部分和关于有意偏离约定的结语