Front-End-Checklist 的 aria-command-name 规则：为 ARIA 命令元素提供可访问名称的完整实践指南

本篇指南以 Front-End-Checklist 仓库中的 aria-command-name 技能文档为主体，系统讲解该规则要求的核心内容：如何让 button、link、menuitem 等"命令类"交互元素具备可编程判定的可访问名称（accessible name），并覆盖正确的代码写法、aria-label / aria-labelledby 的适用场景、异常边界判断、验证方法（自动化 + 手动），以及该技能文件在仓库中的生成机制与关联规则体系。读完后，你可以直接在代码评审、设计系统建设或 AI Agent 辅助审计中应用这条规则，并知道如何用辅助技术验证修复效果。

规则定位：屏幕阅读器用户的"不可命名控件"问题

SKILL.md 开头给出的问题陈述是整个规则的依据：

Without an accessible name, screen reader users will only hear the role (e.g., 'button') without knowing what it does, making the interface impossible to navigate.

也就是说，命令类元素（command elements，即会执行某个动作的交互控件，如按钮、链接、菜单项）如果缺少可访问名称，屏幕阅读器用户聚焦该元素时只能听到"按钮"这类角色播报，完全无法知道它的作用，界面等于无法导航。

该规则在仓库中的元数据如下（来自 SKILL.md 的 frontmatter 与 规则源文件）：

字段	取值	含义
category	accessibility	属于无障碍类别，细分类别（subcategory）为 aria
priority	medium	中等优先级
difficulty	intermediate	中等难度
estimatedTime	10	预计处理耗时 10 分钟
source	frontendchecklist.io	规则来源站点

规则的一句话描述为：Checks that command elements like buttons and links have accessible names for screen reader support.（检查按钮、链接等命令元素是否为屏幕阅读器提供可访问名称。）

技能文件结构：SKILL.md 与 references/rule.md 的双文件体系

该技能目录包含两个文件，二者分工明确：

• skills/aria-command-name/SKILL.md：面向 AI Agent 的"技能入口"，frontmatter 的 description 以 Use when ... 开头，用于 Agent 的意图匹配；正文由 Quick Reference、Check、Fix、Explain、Code Review 五个小节组成，都是可直接执行的指令式内容。
• skills/aria-command-name/references/rule.md：完整规则参考，包含代码示例、Why It Matters、Exceptions、Standards、Verification 等章节，正文内容与 规则源文件 一致。

从源码结构看，这两个文件并非手写，而是由生成脚本 scripts/generate/generate-skills.ts 从 MDX 规则文件自动生成：

• buildSkillMd() 函数将 frontmatter 中的 aiContext/description、tldr（映射为 Quick Reference 小节）、prompts（映射为 Check / Fix / Explain / Code Review 小节）拼装为 SKILL.md，并在 description 不足 50 字符时自动补全、强制以 Use when 开头；
• buildReferencesMd() 函数将 MDX 正文经 stripMdxToMarkdown() 剥离 JSX 语法后，输出为 references/rule.md；
• 当两个分类出现同名 slug 时，脚本会加分类前缀避免目录冲突（processRuleFile）。

仓库提供两种使用方式：安装整套技能 npx skills add frontendchecklist/skills，或只安装单条规则 npx skills add frontendchecklist/skills --skill aria-command-name；也可在本地通过 pnpm generate:skills 全量重新生成。生成的规则目录还会汇总进 docs/generated/rules-catalog.md，其中本规则位于无障碍（accessibility）分类的命名类条目中。

核心要求：命令元素必须有三条路径之一提供名称

SKILL.md 的 Quick Reference 小节给出三条必须完整记住的要点：

1. 具有命令角色（button、link、menuitem）的元素必须有名称；
2. 可访问名称可以通过文本内容、aria-label、aria-labelledby 三种方式提供；
3. 目的是确保用户明确知道交互元素的用途。

对应的检查（Check）与修复（Fix）指令分别是：

• Check：识别出缺少明确可访问名称的命令角色元素（如 button 或 link）。
• Fix：为所有命令元素添加可访问名称，手段包括内部文本、aria-label 或 aria-labelledby。

references/rule.md 中的基准代码示例覆盖了三种典型情况：

<!-- ✅ Correct: Accessible name via text content -->
<button>Submit Form</button>

<!-- ✅ Correct: Accessible name via aria-label (for icon buttons) -->
<button aria-label="Close dialog">
  <svg>...</svg>
</button>

<!-- ❌ Incorrect: No accessible name (empty or icon-only without label) -->
<button>
  <i class="fa fa-trash"></i>
</button>

结合仓库内同分类的规则 button-name.mdx，三种命名方式的使用边界可以进一步展开：

<!-- ✅ 内部文本：最直接的命名方式 -->
<button type="submit">Subscribe to Newsletter</button>

<!-- ✅ aria-label：图标按钮、无文本内容的场景 -->
<button aria-label="Close modal">
  <svg>...</svg>
</button>

<!-- ✅ aria-labelledby：复用页面上已有可见文本（如描述性 span）作为名称 -->
<span id="save-desc">Save your changes</span>
<button aria-labelledby="save-desc">
  <svg>...</svg>
</button>

<!-- ❌ Bad: 仅有图标、没有任何文本或标签 -->
<button>
  <i class="fa fa-trash"></i>
</button>

其中 aria-labelledby 的写法值得注意：它引用的是已有元素的 id，名称会随被引用文本的变化自动更新，避免了 aria-label 与可见文案重复维护两份的问题。button-name 规则的 Best Practices 还补充了几条命名质量要求，同样适用于本规则：标签要简洁（如 "Search" 而非 "Click here to search our website"）、不要在标签中重复 "Button" 字样（屏幕阅读器会播报角色）、使用文本内容时确认它没有被样式意外隐藏、以及动作（如保存、删除、切换）用 <button>、页面跳转用 <a href>，语义保持一致。

为什么重要：命名缺失的四类实际危害

references/rule.md 的 "Why It Matters" 小节列出了四条理由：

• Clarity（清晰度）：明确告知用户激活该元素后会执行什么操作。
• Navigability（可导航性）：用户可以借助语音命令或浏览屏幕阅读器的控件列表来查找并激活控件——没有名称的控件在列表中不可辨识。
• Inclusion（包容性）：为无法看到视觉图标与视觉线索的用户提供同等体验。
• Avoids Confusion（避免困惑）：防止出现 "unlabeled button"（无标签按钮）体验，而这是最常见的无障碍障碍之一。

这与 aria-labels.mdx（"Provide accessible names for all interactive elements"，优先级 high）形成呼应：后者关注所有交互元素，且额外强调避免 "Click Here"、"More" 这类泛化名称——对屏幕阅读器用户而言，这些元素是"mystery meat"（无法辨识意图的交互块），通过元素列表浏览时无法自信地做出交互决策。

异常与边界：何时"不算"这条规则的失败

规则文档的 Exceptions 小节给出了三条重要的判断边界，直接决定审计时的误报率：

1. 优先使用原生 HTML 语义，能用原生元素就不要上 ARIA：很多看似 ARIA 命名失败的问题，在修正底层元素（比如把带 role="button" 的 <div> 换回真正的 <button>）后会自动消失。
2. 缺少 ARIA 属性本身不一定是最强问题：如果控件的语义已经损坏、完全没有名称、或者键盘不可达，那么"缺 ARIA 命名属性"只是表象，应优先修复更根本的问题。
3. 不要为了通过规则而添加 ARIA：如果功能本应改用原生元素或更简单的交互模式实现，就不应靠补一个 aria-label 来"过关"。

这三条边界也体现在 SKILL.md 的 description（由 MDX frontmatter 的 aiContext 生成）中："Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output where relevant."——即审查顺序是：先看原生语义，再看键盘行为、焦点流、可访问名称和屏幕阅读器输出。

验证方法：自动化检查 + 手动验证

规则文档明确要求"verify the rendered experience, not only the source code"（验证渲染后的实际体验，而不只是源码），并给出两类验证手段：

自动化检查（Automated Checks）

• 打开浏览器的 accessibility tree（无障碍树）/ Accessibility 面板，检查相关元素的角色（role）与可访问名称是否符合预期；
• 运行自动化无障碍检查工具，如 axe 或 Lighthouse（规则源文件将 axe DevTools 列为 resources 工具）。

手动检查（Manual Checks）

• 仅用键盘导航测试受影响的 UI，确认规则在渲染后的体验中成立；
• 如果该规则影响关键交互路径，用屏幕阅读器重测一条代表性用户流程。

标准依据方面，文档对齐 WAI-ARIA 1.2 规范与 MDN: ARIA 文档（见 aria-command-name.mdx 的 sources 字段，role 分别为 standard 与 reference，authority 均为 primary）。

Agent 工作流：Check / Fix / Explain / Code Review 四段式指令

SKILL.md 的主体是四段面向 Agent 的指令，这套结构是该仓库所有规则技能共有的模板（由 generate-skills.ts 统一从 frontmatter 的 prompts 字段生成），但每条规则的措辞针对其自身领域定制：

小节	本规则的具体指令
Check	识别出缺少明确可访问名称的命令角色元素（如 button 或 link）
Fix	用内部文本、aria-label 或 aria-labelledby 为所有命令元素添加可访问名称
Explain	解释命令元素的可访问名称如何帮助屏幕阅读器用户理解交互控件
Code Review	审查渲染后的标记与交互状态；精确指出违规的元素、角色、标签、焦点行为或键盘交互，并说明如何用浏览器无障碍工具或辅助技术验证修复

注意 Code Review 指令中的关键约束：要求 Agent "Flag exact elements"（精确标记具体元素），并且必须给出验证路径（browser accessibility tooling 或 assistive tech），而不是泛泛建议"加个 label"。这保证了审计结论可定位、可复现。

在规则体系中的位置：命名类规则族

从 aria-command-name.mdx 的 relatedRules 字段与目录结构看，本规则属于无障碍分类下"可访问命名"规则族的一员，各规则按元素/角色切分：

关联规则	文件	关注点
aria-labels（high）	aria-labels.mdx	所有交互元素的命名，含名称质量（避免泛化文案）
button-name（critical）	button-name.mdx	按钮命名 + 动作/导航语义一致性
aria-dialog-name	aria-dialog-name.mdx	对话框元素的命名
aria-treeitem-name	aria-treeitem-name.mdx	role="treeitem" 元素的命名
aria-input-field-name	aria-input-field-name.mdx	输入字段的命名
aria-meter-name	aria-meter-name.mdx	meter 测量元素的命名

这些规则的 Exceptions、Standards、Verification 章节模板一致（均要求验证渲染体验、优先原生语义），差异集中在元素类型与命名示例上。实际评审时，按钮命名问题通常由 critical 级的 button-name 规则主导，aria-command-name 则作为 medium 级规则兜底覆盖 menuitem 等 ARIA 角色场景——这也是仓库在 docs/generated/rules-catalog.md 中为它们分别标注优先级徽标的原因。

小结

aria-command-name 规则的核心命题很简单：命令元素必须拥有可编程判定的名称。其工程价值体现在三个层面——提供了可复制的正反代码示例与三种命名方式的适用边界；给出了 Exceptions 三条判断边界，帮助审计者避免"为加 ARIA 而加 ARIA"的误修；以及给出了"自动化检查 + 键盘/屏幕阅读器手动验证"的闭环验证路径。在 Front-End-Checklist 仓库中，该规则以 MDX 源文件为单一事实来源，经脚本生成为 Agent 可消费的技能文件（SKILL.md + references/rule.md），可直接通过 npx skills add frontendchecklist/skills --skill aria-command-name 安装使用，也可在代码评审时对照上述四段式指令逐条检查。