企业官网建设流程全解析

Front-End-Checklist 的 accesskeys 技能：如何保证页面 accesskey 快捷键值唯一

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist

本篇以skills/accesskeys/SKILL.md这份 Agent 技能文档为核心，讲解 Front-End-Checklist 项目中 "Ensure accesskey values are unique" 规则的完整检查、修复与验证方法。读完你可以掌握：accesskey重复导致的键盘可访问性冲突原理、可复制的合规 HTML 写法，以及该技能文档在项目规则体系（MDX 规则源文件、生成脚本、质量审计）中的位置与使用方式。

技能文档的定位与结构

SKILL.md 是 Front-End-Checklist 为 AI Agent 提供的一条可执行评审技能。它由规则的 MDX 源文件 accesskeys.mdx 通过 generate-skills.ts 自动生成，目录结构遵循skills/{slug}/SKILL.md + references/rule.md的统一模式。

SKILL.md 的 frontmatter 声明了技能的元信息，直接对应规则源文件中的字段：

--- name: accesskeys description: "Use when reviewing rendered HTML, interactive components, or design-system patterns related to Ensure accesskey values are unique..." metadata: category: accessibility # 所属类别：可访问性 priority: medium # 优先级：中等 difficulty: intermediate # 难度：中级 estimatedTime: "10" # 预估处理耗时 10 分钟 source: frontendchecklist.io ---

从 generate-skills.ts 的buildSkillMd实现可以看到，description字段会被强制改写为以 "Use when" 开头的意图匹配格式（skill-check 规范要求），且长度不足 50 字符时会自动追加title (category)补齐——这正是本文 frontmatter 中description呈现为 "Use when reviewing rendered HTML..." 的原因。

问题本质：重复的 accesskey 会造成什么

accesskey属性允许开发者为特定元素绑定键盘快捷键。规则的核心约束是：每个accesskey值在文档内必须唯一。

规则说明（来自 accesskeys.mdx 的whyItMatters字段）：重复的 access key 会引发冲突，通常只有第一个元素能通过快捷键到达，其余元素对键盘用户而言实际上不可访问。

SKILL.md 的 "Quick Reference" 小节把要点压缩为三条：

• 页面上每个accesskey属性值必须唯一
• 重复的 access key 会导致不可预测的浏览器行为
• 保证键盘用户能可靠地通过定义好的快捷键导航

代码示例：正确与错误的写法

references/rule.md 给出了一组可直接对照的 HTML 示例：

<!-- ✅ 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>

错误示例中 "Save" 与 "Search" 共用了accesskey="s"，快捷键s只能命中其中一个元素（通常为文档顺序靠前者），另一个入口对键盘用户失效。

为什么重要：四个维度的影响

references/rule.md 的 "Why It Matters" 一节从四个角度说明了该规则的价值，这些内容同样继承自 MDX 源文件：

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

Check / Fix / Explain：技能的四段式操作指令

SKILL.md 将规则操作拆解为四个小节，每一节都是可直接交给 Agent 执行的指令：

其中 Code Review 小节体现了该项目技能文档的通用方法论（与源文件 frontmatter 中aiContext一致）：先检查原生语义，再检查键盘行为、焦点流、可访问名称和屏幕阅读器输出。

例外情况：不要机械地把静态代码味当阻断项

references/rule.md 的 "Exceptions" 一节给出了三条判定边界，对实际评审很有参考价值：

• 先把渲染后的体验评估清楚，再决定是否把静态代码问题当作阻断项——交互时机、浏览器行为、辅助技术输出往往决定严重级别；
• 不是每个次要可访问性问题都值得同等权重，应优先处理最直接阻塞感知、操作或理解的问题；
• 当更简单的语义化实现能彻底消除问题时，不要为了凑规则而添加冗余标记或 ARIA。

标准依据与验证手段

规则对齐两个标准来源（见 MDX 源文件sources字段与 rule.md "Standards" 一节）：W3C WAI 的 WCAG 概述（role: standard，authority: primary）与 MDN 的 Accessibility 文档（role: reference，authority: primary）。两者的共同要求是：验证渲染后的体验，而不只是源代码。

验证分两条路径：

自动化检查

• 检查浏览器可访问性树 / DevTools 的 Accessibility 面板中相关元素的角色与可访问名称；
• 在适用场景运行 axe 或 Lighthouse 等自动化工具（resources字段将 axe DevTools 列为配套工具）。

手动检查

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

技能在仓库体系中的生成与维护

这份 SKILL.md 不是手写文件，而是 generate-skills.ts 的产物，理解这条链路有助于维护：

• 规则源文件：packages/content/rules/en/accessibility/accesskeys.mdx，frontmatter 携带title、tldr、prompts（check/fix/explain/codeReview）、sources、relatedRules等字段；
• 全量生成：pnpm generate:skills遍历packages/content/rules/en下所有 MDX，生成skills/{slug}/SKILL.md与skills/{slug}/references/rule.md，其中 MDX 正文经stripMdxToMarkdown剥离 JSX/import/export 后转为纯 Markdown；
• 增量生成：lefthook 钩子会将暂存的 MDX 文件作为参数传给同一脚本，只重新生成变更规则对应的技能；
• slug 冲突处理：findDuplicateSlugs会检测跨类别重名 slug，冲突时自动加类别前缀，保证name_matches_directory规则成立；
• 质量审计：pnpm skills:audit运行 skills-quality-audit.ts 对 skills 目录做质量检查。

技能对外的安装入口（见 generate-skills.ts 文件头注释）为：

npx skills add frontendchecklist/skills npx skills add frontendchecklist/skills --skill accesskeys # 仅安装本技能

该规则在规则目录 rules-catalog.md 与 README.md 的可访问性清单中均以 "Medium" 优先级列出，其relatedRules字段还关联了frame-title、touch-targets、color-contrast、focus-styles四条同属accessibility/visual领域的规则，评审键盘与可访问性时通常应一并检查。

小结

skills/accesskeys/SKILL.md把 "accesskey 值必须唯一" 这条规则打包成了结构完整的 Agent 技能：frontmatter 承载意图匹配与元数据，Check/Fix/Explain/Code Review 四段指令覆盖从检测到修复到解释的全流程，references/rule.md则补足了代码示例、影响分析、例外边界、标准依据和验证手段。评审时的关键动作很明确：在渲染后的页面上确认每个accesskey值只出现一次，用键盘走一遍快捷键流程，必要时用 axe、Lighthouse 与屏幕阅读器交叉验证；若语义化改造即可消除重复，则优先选择更简单的实现。

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist