Front-End-Checklist aria-allowed-attr 技能解析：让每个 ARIA 角色只使用其允许的 ARIA 属性

本文围绕 Front-End-Checklist 仓库中的 skills/aria-allowed-attr 技能文档展开，讲解"每个 ARIA 角色只应使用其允许的 ARIA 属性"这一可访问性规则的审查方法、正确/错误示例、例外场景与验证手段。读完本文，你可以掌握如何在代码审查与 Agent 辅助开发流程中检查 ARIA 属性与角色的匹配关系，并利用本仓库的规则定义、MCP 工具与生成脚本将其落地为可执行的审查流程。

规则定位与技能文件结构

aria-allowed-attr 是 Front-End-Checklist 可访问性（accessibility）分类下 aria 子分类中的一条规则，聚焦于"检查元素上使用的 ARIA 属性是否被其 WAI-ARIA 角色所允许"。规则核心问题在于：ARIA 属性必须与其所在元素的角色相匹配，使用不属于该角色的属性会造成"静默失败"（silent failures）——无障碍信息被屏幕阅读器无声地丢弃，用户感知不到任何报错，体验却已损坏。

技能由两部分组成：

• SKILL.md：面向 Agent 的技能入口，包含 name、description、metadata 等 frontmatter 元数据，以及 Check / Fix / Explain / Code Review 四段式审查指令；
• rule.md：完整规则正文，包含代码示例、重要原因、例外、标准对齐与验证步骤。

SKILL.md 的 frontmatter 元数据如下：

name: aria-allowed-attr
metadata:
  category: accessibility
  priority: medium
  difficulty: intermediate
  estimatedTime: "10"
  source: frontendchecklist.io

即该规则优先级为 medium、难度 intermediate、预计审查耗时 10 分钟。description 字段明确要求"Use when reviewing rendered HTML, interactive components, or design-system patterns"，并给出审查顺序：先检查原生 HTML 语义，再检查键盘行为、焦点流、可访问名称和屏幕阅读器输出。

从源码结构看，这类技能文件并非手工编写，而是由 generate-skills.ts 从规则 MDX 的 frontmatter 自动生成的：脚本读取 packages/content/rules/en 下的规则文件，将每个规则转换为 skills/{category}/{slug}/ 目录，SKILL.md 承载名称、描述与提示词，references/rule.md 则是规则 MDX 正文转成的纯 Markdown。脚本还专门处理了 description 必须以 "Use when" 开头（供 Agent 意图匹配）以及描述长度不足 50 字符时自动补全的约束。因此，修改规则正文后重新运行生成脚本即可保持技能文件与规则定义一致，这也是理解该仓库"规则即数据、技能即派生物"设计思路的关键。

该规则的权威定义位于 aria-allowed-attr.mdx，其 frontmatter 中声明了 prompts（check/fix/explain/codeReview 四段提示词）、sources（对齐 WAI-ARIA 1.2 规范与 MDN 的 ARIA 文档）、resources（axe DevTools 工具）以及 relatedRules（aria-required-attr、aria-required-children、aria-hidden-body、decorative-elements 等常一起审查的规则）。

核心原则：角色决定允许的 ARIA 属性集合

WAI-ARIA 规范为每种角色定义了"允许属性"（allowed attributes）与"必须属性"（required attributes）两套约束。本规则对应的是前者：

• 每个 ARIA 角色只支持一组特定的 ARIA 属性；
• 使用角色不支持的属性会干扰辅助技术（Assistive Technology）对元素状态与用途的解读；
• 保持"角色-属性"匹配，才能保证浏览器生成的可访问性树（accessibility tree）有效且语义完整。

原文档给出的标准代码示例如下：

<!-- ✅ Correct: aria-checked is allowed on checkbox role -->
<div role="checkbox" aria-checked="true" tabindex="0">Subscribe</div>

<!-- ❌ Incorrect: aria-checked is NOT allowed on a heading role -->
<h1 role="heading" aria-checked="true">Main Title</h1>

第一例中 aria-checked 是 checkbox 角色的必须属性之一，使用完全合法；第二例中 heading 角色不允许任何状态类属性，aria-checked 会被屏幕阅读器忽略或引发误读——标题不应表达"勾选状态"，这是语义层面的错配。

审查时应遵循 rule.md 中给出的三段式指令：

1. Check（检查）：验证元素上所有 ARIA 属性是否与其被分配的 WAI-ARIA 角色匹配；
2. Fix（修复）：删除或修正不被元素当前 ARIA 角色支持的属性；
3. Explain（解释）：说明为什么只有角色支持的 ARIA 属性才能保证屏幕阅读器正确通信。

为什么这条规则重要

原文档从四个维度给出了理由，可访问性审查中这四点是说服团队接受整改的依据：

• Standard Compliance（标准合规）：遵循 WAI-ARIA 规范，构建健壮、可预测的 Web 应用；
• AT Accuracy（辅助技术准确性）：保证屏幕阅读器收到关于元素状态的正确、相关信息；
• Reduced Noise（减少噪声）：阻止开发者向 DOM 中堆入冗余、无效或令人困惑的元数据；
• Future Compatibility（未来兼容性）：规范的 ARIA 用法让应用随着浏览器和屏幕阅读器实现的演进而持续可用。

值得强调的是"静默失败"这一特性：无效 ARIA 属性不会抛错、不会在控制台报警告，唯一的表现是辅助技术拿到缺失或错误的信息。这与运行时 JavaScript 报错截然不同，因此必须依赖规范化的审查流程和自动化工具来兜底。

例外与优先级判断

rule.md 的 Exceptions 一节给出了三条重要的边界条件，避免审查时机械执行规则：

• 优先原生 HTML 语义：当原生元素与 ARIA 二选一都可行时，优先原生 HTML。很多表面上的 ARIA 违规（例如给 <div> 硬加一堆 aria-* 属性来模拟按钮），在把底层元素换成 <button> 后自然消失；
• 属性缺失未必是最强发现：如果一个控件本身已经语义损坏、缺少可访问名称或不可键盘访问，那么"缺少某个 ARIA 属性"不是最严重的问题——应优先上报更根本的缺陷；
• 不要为凑规则而加 ARIA：如果某个功能本应使用原生元素或更简单的交互模式实现，就不要单纯为满足规则而补 ARIA 属性。

这三条与 SKILL.md 中"先检查原生语义"的审查顺序呼应：本规则的正确打开方式是减法（删掉错误属性、回归原生语义），而不是加法（继续堆属性）。

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

规则文档将验证分为两类，实际操作建议组合使用：

自动化检查

• 检查浏览器可访问性树 / 可访问性面板中相关元素的角色、状态与可访问名称——现代浏览器开发者工具均内置该面板，能直接观察属性被引擎解析后的实际结果；
• 运行 axe 或 Lighthouse 等自动可访问性检查器（规则的 frontmatter 中也将 axe DevTools 列为推荐工具）。

手动检查

• 仅用键盘操作受影响的 UI，确认规则在真实渲染结果中成立（Tab 顺序、焦点可见性、状态播报）；
• 若规则影响关键交互，用屏幕阅读器重测一条代表性用户流程。

标准对齐要求来自 aria-allowed-attr.mdx 的 Sources 部分：以 WAI-ARIA 1.2 规范与 MDN 的 ARIA 文档为参照，且验证的是渲染后的体验，而不是只看源码——同一份源码在不同渲染框架下可能产生不同的可访问性树，这一点在审查框架组件（React/Vue 组件、设计系统封装件）时尤为重要。

仓库中的工程化支撑：从规则定义到 Agent 可调用工具

在 Front-End-Checklist 仓库中，这条规则不仅是文档，还是一套可被程序消费的工程资产，形成"规则定义 → 站点页面 → Agent 技能 → MCP 工具"的完整链路：

1. 规则定义层：aria-allowed-attr.mdx 的 frontmatter 是唯一事实来源，包含 check/fix/explain/codeReview 提示词、引用标准、工具与关联规则；
2. 技能生成层：generate-skills.ts 将其派生为 skills/aria-allowed-attr/SKILL.md，可被支持 Agent 技能机制的工具安装使用；
3. MCP 工具层：仓库内置的 MCP 服务提供 check_rule 工具，定义见 check-rule.ts。该工具接收规则 slug（如 aria-allowed-attr）与可选的代码片段：不带代码时返回验证指引，带代码时执行启发式分析并报告合规状态，发现问题时附带 fix prompt 供直接整改。工具描述中明确了工作流：先用规则搜索工具找到相关规则，再用 check_rule 核对，必要时用 fix/explain 类工具跟进；
4. 关联规则层：frontmatter 中声明了 aria-required-attr（角色必须属性）、aria-required-children（必须子节点）、aria-hidden-body、decorative-elements 等常一起审查的规则。实际审查中"属性允许"（本规则）与"属性必需"（aria-required-attr）互为镜像：一个管"多了不该有的"，一个管"少了该有的"，两者都通过才谈得上角色完整合规。

这一结构意味着：当你在自己的项目审查流程中遇到 ARIA 角色-属性匹配问题时，可以直接以 slug aria-allowed-attr 为入口调用上述工具链，获取与本仓库完全一致的判定口径与修复指引。

小结

aria-allowed-attr 规则虽然条目简短，但对应的是可访问性树有效性的一层硬性约束：ARIA 属性必须落在其角色允许的属性集合内，否则屏幕阅读器会静默地丢失或误读信息。落地审查时的完整动作序列是——先确认能否用原生元素替代（例外优先），再逐元素核对角色与属性的允许关系，随后通过浏览器可访问性面板、axe/Lighthouse 自动化检查以及键盘加屏幕阅读器手动测试三重验证渲染结果。在 Front-End-Checklist 仓库中，这套流程已从静态文档演进为可生成、可检索、可经 MCP 工具调用的工程化资产，适合作为人工 Code Review 与 Agent 辅助审查的共同基准。