企业官网建设流程全解析

Front-End-Checklist 的 ARIA 角色属性匹配规则：aria-allowed-attr 审查技能深度解析

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

Front-End-Checklist 是面向人类开发者与 AI Agent 的现代 Web 开发检查清单项目，本文聚焦其中的可访问性规则aria-allowed-attr——要求每个 ARIA 角色只使用其被允许的属性。读完本文，你将理解该规则背后的 WAI-ARIA 规范原理、完整正反例、异常边界与验证方法，并掌握它在仓库中从 MDX 规则源文件生成 Agent 技能（Skill）的完整链路。

规则定位与元数据

该规则在检查清单体系中的定位如下（元数据来自 规则 MDX 源文件 的 frontmatter，并同步写入 技能参考文档）：

规则的一句话描述是：检查 ARIA 属性是否被其所在元素的角色所允许，以确保生成合法的无障碍树（accessibility tree）。其核心动机（来自 frontmatter 的whyItMatters字段）是：无效的 ARIA 属性会被屏幕阅读器忽略，甚至可能让辅助技术误解元素用途，最终导致视障用户获得断裂的交互体验。

核心原理：角色决定属性许可集

ARIA 属性的合法性有两层判定：属性名本身必须存在于 WAI-ARIA 规范中；同时，属性必须被元素当前扮演的 role 所允许。本规则关注的是第二层——即使aria-checked是合法属性，它也只能出现在checkbox、menuitemcheckbox、option、radio等支持该状态的角色上，而不能随意贴到任意元素上。

原文档用如下代码示例说明这一区分：

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

第一个示例中，div被显式声明为checkbox角色，aria-checked正是该角色的状态属性，因此无障碍树能正确表达"已勾选"状态；配合tabindex="0"使元素可聚焦，才构成一个可用的复选框交互。第二个示例把aria-checked加在heading角色上，而heading角色的允许属性集合中并不包含aria-checked——该属性会被浏览器/辅助技术静默丢弃，形成文档所称的"silent failures"：源码看似写了无障碍标注，实际信息却在渲染后的无障碍树中丢失，且没有任何报错提示。

这里还有一层值得注意的语义陷阱：<h1>本身已隐含heading角色，显式书写role="heading"属于冗余标注。按本规则配套的 aria-roles 规则 的思路，能用原生语义就不用 ARIA 复述，这也是下文"例外"第一条的由来。

为什么这条规则重要

原文档给出的四点价值陈述完整保留如下，它们解释了规则在medium而非high优先级下的取舍逻辑：

• 标准合规（Standard Compliance）：遵循 WAI-ARIA 规范，使 Web 应用的行为健壮且可预期。
• 辅助技术准确性（AT Accuracy）：确保屏幕阅读器等辅助技术收到的是与元素状态真正相关的信息，而不是被静默忽略或误读。
• 降低噪音（Reduced Noise）：阻止开发者向 DOM 中添加冗余、无效或令人困惑的元数据，保持无障碍树干净。
• 未来兼容性（Future Compatibility）：浏览器和屏幕阅读器的实现会持续演进，合法的 ARIA 用法能确保应用在这些实现变化中保持可访问。

其中"降低噪音"一点尤其体现该仓库的工程取向：多余的 ARIA 标注不仅无益，还会在无障碍树中制造虚假语义节点，干扰屏幕阅读器用户的导航。

例外与边界判断

规则文档明确列出了三条例外，这些内容对人工审查和 Agent 自动审查都同样重要：

1. 优先使用原生 HTML 语义：当原生元素与 ARIA 二选一时，选原生元素。部分看似"ARIA 属性用错"的问题，把底层元素修正后（例如把模拟复选框的div换成真正的<input type="checkbox">）就自然消失。
2. 缺失属性不一定是最强发现：如果一个控件本身已存在语义破坏、缺少可访问名称或无法键盘访问，那么"某个 ARIA 属性缺失"就不是应当排在最前面的问题。
3. 不要为通过规则而添加 ARIA：如果某个功能本应改用原生元素或更简单的交互模式实现，就不应该靠补 ARIA 属性来"满足检查"。

这三条边界与 SKILL.md 中给 Agent 的aiContext指导一致：审查渲染后的 HTML、交互组件或设计系统模式时，先检查原生语义，再检查键盘行为、焦点流、可访问名称和屏幕阅读器输出。

标准依据

规则要求在两个标准层面验证实现，且都强调"验证渲染后的体验，而不只是源代码"：

• 与WAI-ARIA 1.2规范对齐（frontmatter 中以role: standard、authority: primary标注为主标准来源）；
• 与MDN: ARIA参考对齐（标注为type: mdn的参考来源）。

frontmatter 中还声明了一个工具资源：axe DevTools（type: tool），用于自动化检测。

验证方法

原文档把验证分为自动化与手动两条路径，二者结合才能确认"角色-属性匹配"在真实渲染环境中成立：

自动化检查

• 在浏览器 DevTools 的无障碍面板（Accessibility pane）或无障碍树中，检查目标元素的role属性输出——注意是渲染后的 computed role，而非源码上写着的role属性，某些属性违规会导致整个角色回退（role fallback）；
• 在适用场景下运行 axe 或 Lighthouse 等自动化工具。axe 的 ARIA 规则集（如aria-allowed-attr检查项）正是这条清单规则名称的直接来源。

手动检查

• 仅用键盘导航受影响的 UI，确认规则在渲染后的体验中成立（聚焦是否落在正确元素上、状态是否可通过方向键/空格切换并被读屏软件播报）；
• 如果该规则影响关键交互（如表单提交、菜单展开），用一个代表性的用户流程配合屏幕阅读器复测。

仓库实现：从 MDX 规则到 Agent 技能

本规则的"技能形态"不是手写的，而是由仓库的生成管线产出。理解这条链路有助于在 Front-End-Checklist 中定位和引用规则：

1. 规则源文件：aria-allowed-attr.mdx 位于packages/content/rules/en/{category}/{slug}.mdx结构下，frontmatter 携带title、categories、priority、prompts（check/fix/explain/codeReview 四段式提示词）、sources、relatedRules等字段，正文即上文引用的代码示例与验证章节。
2. 技能生成脚本：generate-skills.ts 读取每个 MDX 的 frontmatter，剥离 MDX/JSX 语法后，为每条规则生成skills/{slug}/目录：SKILL.md由buildSkillMd()组装（name、以 "Use when" 开头的 description、metadata、Quick Reference、Check/Fix/Explain/Code Review 四节），references/rule.md由buildReferencesMd()组装——即元数据头 + 完整正文。references/rule.md 就是本条规则的全量参考文档，与 SKILL.md 互为索引。
3. 规则运行时加载：load-rules.ts 的loadRules()扫描规则目录，用轻量 YAML 解析提取title、priority、subcategory、categories、prompts，产出符合 types.ts 中FrontendChecklistRule接口的记录，供 MCP 工具（如get_rule、fix_rule、explain_rule）与站点检索消费。

以本规则为例，其四段式 prompts 在 SKILL.md 中呈现为可直接执行的指令：

• Check：验证元素上使用的每个 ARIA 属性是否与其被指派的 WAI-ARIA 角色兼容；
• Fix：移除或更正不被元素当前角色支持的 ARIA 属性；
• Explain：解释为何只有角色支持的属性才能被屏幕阅读器正确解读；
• Code Review：审查渲染后的标记与交互状态，指出具体违反规则的元素、角色、标签、焦点行为或键盘交互，并说明如何用浏览器无障碍工具或辅助技术验证修复。

此外，该规则的relatedRules字段声明了四条常一起审查的邻近规则（均来自accessibility/aria子域）：aria-required-children、decorative-elements、aria-hidden-body、aria-required-attr。注意与 aria-valid-attr 的分工：后者（priority: high）管"属性名是否存在于规范"，本规则（priority: medium）管"属性是否匹配角色"，两者共同构成 ARIA 合法性的完整校验面。完整规则清单可在 rules-catalog 中检索到该条目的索引信息。

实战要点小结

• 审查顺序上，先问"能否用原生元素替代"，再问"角色是否正确"，最后才检查"角色是否允许该属性"——前两步消除问题后，很多 ARIA 属性违规会自动消失；
• 判定依据以渲染后的无障碍树为准：DevTools Accessibility 面板显示的 computed role 和属性列表是最终事实，源码中的role属性可能是冗余甚至无效的；
• 修复时优先删除违规属性或改用原生控件，而不是叠加更多 ARIA 来"打补丁"；
• 修复后的验证闭环 = 键盘导航 + 无障碍面板复查 +（关键交互时）一次屏幕阅读器走查。

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