Front-End-Checklist 中的 accesskey 唯一性规则：无障碍规则文档的结构、校验方法与源码级生成机制

本篇指南围绕 accesskeys 规则参考文档 展开，讲解 accesskey 键盘快捷键唯一性这条无障碍检查规则的核心概念、正确/错误代码示例、例外判断标准与验证手段，并结合 Front-End-Checklist 仓库的源码与生成脚本，还原这条规则从 MDX 源文件到 Agent 技能（Skill）产物的完整数据链路，读完后可掌握该规则的实战检查方式，以及规则文档在仓库内的组织与生成机制。

这条规则检查什么

accesskey 属性允许开发者为页面上的特定元素绑定键盘快捷键。为了让这些快捷键可靠工作，每个 accesskey 值在文档内必须是唯一的。该规则在仓库中的定位信息如下（见 rule.md 与源规则 frontmatter）：

元数据	取值	说明
规则标题	Ensure accesskey values are unique	确保 accesskey 值唯一，避免快捷键冲突
分类	accessibility / visual	属于可访问性检查项，与视觉呈现类规则同组评审
优先级（priority）	medium	中等优先级
难度（difficulty）	intermediate	中级难度
预计耗时（estimatedTime）	10 min	预估 10 分钟完成检查与修复

规则描述的核心风险在 SKILL.md 中概括得很直接：重复的 accesskey 会导致冲突，通常只有其中一个元素（一般是文档中第一个）能通过该快捷键触达，其余元素对键盘用户而言就等于“失联”。

正确与错误示例

原文档给出的对照示例是理解本规则的最短路径，完整继承如下：

<!-- ✅ Correct: Unique access keys -->
<a href="/home" accesskey="h">Home</a>
<a href="/contact" accesskey="c">Contact</a>

<!-- ❌ Incorrect: Duplicate access keys -->
<a href="/save" accesskey="s">Save</a>
<a href="/search" accesskey="s">Search</a>

两段示例的差异仅在于 accesskey 的取值是否重复：第一组中 h 与 c 各自唯一，快捷键行为可预期；第二组中 Save 与 Search 两个链接共用 s，按下快捷键时具体落在哪个元素上取决于浏览器实现，键盘用户可能得到与预期完全不同的导航结果。

为什么唯一性重要

原文档的 Why It Matters 一节从四个维度解释了这条规则的价值，逐条继承如下：

• 可预测的导航（Predictable Navigation）：保证键盘快捷键按预期工作，不产生冲突；
• 辅助技术兼容性（Assistive Technology）：屏幕阅读器等辅助技术依赖唯一标识进行可靠交互；
• 用户体验（User Experience）：避免快捷键触发错误动作、焦点跳到错误元素时带来的挫败感；
• 浏览器一致性（Browser Consistency）：不同浏览器对重复 accesskey 的处理方式各不相同，唯一性保证了跨平台体验一致。

其中最后一点值得展开：accesskey 在主流浏览器中的触发前缀（Windows 上是 Alt、macOS Safari 上是 Ctrl+Option 等）本身就存在平台差异，若再叠加重复值，行为不确定性会进一步放大。因此该规则本质上是在用“值唯一”这一静态约束，抵消运行时的平台差异。

例外与严重度判断

原文档 Exceptions 一节给出了三条判断准则，用于避免把静态代码异味机械地当作阻塞性问题：

1. 在把静态代码异味当作 blocker 之前，先评估渲染后的真实体验——交互时序、浏览器行为、辅助技术输出往往共同决定严重度；
2. 并非每个次级可访问性问题都值得同等权重，应优先处理最直接阻碍感知、操作或理解的问题；
3. 不要为了通过规则而添加冗余标记或 ARIA——如果更简单的语义化实现能彻底消除问题，优先选择后者。

这三条准则体现了 Front-End-Checklist 的一贯立场：校验渲染后的体验，而不只是源码文本（该立场也出现在原文档 Standards 一节的措辞中）。

如何验证规则是否成立

原文档 Verification 一节区分了自动化与手工两类检查手段：

自动化检查

• 检查浏览器无障碍树（accessibility tree）或无障碍面板，定位相关元素的 role 与 accessible name；
• 在适用时运行 axe 或 Lighthouse 等自动化无障碍检查工具（源规则 frontmatter 的 resources 字段中显式关联了 axe DevTools 这一工具资源）。

手工检查

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

结合源码可以补充一个实操视角：检测重复 accesskey 的核心逻辑是“全文档范围内按值分组”。对纯 HTML 项目可以直接用 DevTools 控制台执行一条查询，例如按 document.querySelectorAll('[accesskey]') 收集属性值并统计重复项；对于由组件库生成的页面，则应聚焦在组件模板层——同一个组件被复用时若各自硬编码了相同 accesskey，重复会在实例数量增长后批量出现，这正是该规则难度被标为 intermediate 而非 beginner 的原因。

仓库级溯源：从 MDX 源规则到 Skill 产物

该参考文档并非手写文件，而是仓库生成流水线的产物，完整理解其来源有助于判断内容可信度与更新方式。

源规则文件

accesskeys.mdx 是这条规则的单一事实来源，位于 packages/content/rules/en/accessibility/ 目录下。其 frontmatter 除与 rule.md 一致的 priority、difficulty、estimatedTime 外，还包含参考文档未展开的结构化字段：

• tldr：三条要点式结论（每个 accesskey 值在页面内必须唯一、重复会导致不可预期的浏览器行为、帮助键盘用户可靠导航）；
• whyItMatters：重复 accesskey 造成冲突，通常只有第一个元素可通过快捷键触达；
• prompts：check / fix / explain / codeReview 四段式 Agent 提示词，即 SKILL.md 中 Check、Fix、Explain、Code Review 小节的直接来源；
• aiContext：指导 Agent 在评审渲染后的 HTML、交互组件或设计系统模式时如何应用该规则（先查原生语义，再检查键盘行为、焦点流、accessible name 与屏幕阅读器输出）；
• sources：关联 W3C WAI 的 WCAG 概览（standard / primary 权威级）与 MDN 的 Accessibility 参考（reference / primary 权威级）——这对应参考文档 Standards 一节引用的两份标准；
• relatedRules：列出 frame-title、touch-targets、color-contrast、focus-styles 四条同属 accessibility/visual 分组、通常一起评审的相关规则。

生成流水线

从源码结构看，generate-skills.ts 负责把每条 MDX 规则转换为 skills/{slug}/ 目录下的两份文件：SKILL.md 承载名称、描述与四段式指令；references/rule.md 承载由 MDX 正文剥离 JSX 语法后的完整 Markdown 正文（由 stripMdxToMarkdown 完成，见 generate-skills.ts）。脚本头部注释明确了数据流的两端：

• 输入目录 RULES_DIR 为 packages/content/rules/en（见 generate-skills.ts）；
• 输出目录 OUTPUT_DIR 为 skills，即本文档所在的目录。

因此 rule.md 的正文与 accesskeys.mdx 的正文在内容上是同源的，frontmatter 则被 buildSkillMd 转写为 SKILL.md 的 YAML 头与章节结构。该脚本支持全量生成（pnpm generate:skills）与针对单个规则文件的增量生成，后者被 lefthook 钩子用于提交前校验，保证 MDX 源与 skills 产物不漂移。

在站点与目录中的位置

规则同时被纳入仓库生成的规则目录 rules-catalog.md，其中该条以“Ensure accesskey values are unique”列出并标注 Medium 优先级，说明它既服务于 Agent 技能消费，也服务于站点侧的规则检索。

规则的消费方式

generate-skills.ts 头部注释给出了 skills 产物的安装方式：可按需安装全部技能或单个技能（npx skills add 形式，支持 --skill {slug} 指定如 accesskeys 的单条规则）。消费后，Agent 依据 SKILL.md 中的四段式指令工作：Check（全文档检查重复的 accesskey 属性）、Fix（为每个 accesskey 分配唯一值或删除冗余项）、Explain（解释重复 accesskey 对键盘可访问性与浏览器快捷键处理的影响）、Code Review（在渲染后的标记与交互状态中定位违反规则的具体元素、role、label 与焦点行为，并说明如何用浏览器无障碍工具验证修复）。

小结

• accesskey 值必须在全文档范围内唯一，重复值会让快捷键的落点依赖浏览器实现，破坏键盘用户的可预期导航；
• 验证手段分两层：自动化（无障碍树、axe / Lighthouse）与手工（纯键盘导航 + 屏幕阅读器复测），并遵循“以渲染体验定严重度”的例外准则；
• 该规则文档由 accesskeys.mdx 经 generate-skills.ts 生成，frontmatter 中的 prompts、sources、relatedRules 等字段分别映射为 SKILL.md 指令、标准引用与同组评审规则，形成从单一事实来源到 Agent 技能产物的可追溯链路。