Front-End Checklist 无障碍规则实战修复roletext容器中的可聚焦子元素【免费下载链接】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 仓库中的aria-text无障碍规则展开系统讲解为什么roletext容器内不应包含链接、按钮、输入框等可聚焦元素以及如何在代码审查与前端审计中快速定位、修复并用浏览器无障碍工具验证此类问题。读完本文你将掌握该规则的判定标准、修复手法、豁免场景以及它在仓库中从 MDX 规则源到 Agent Skill 的完整实现链路可直接用于日常开发与 AI 驱动的代码审查。规则定位一条关于语义展平的无障碍规则aria-text规则的全称是Avoid focusable descendants in roletext elements避免roletext元素包含可聚焦后代在仓库中的元数据定义如下见 packages/content/rules/en/accessibility/aria-text.mdx分类accessibility无障碍子类aria优先级medium中等难度intermediate进阶预计耗时10 分钟规则的核心原理一句话可以概括给容器加上roletext会强制屏幕阅读器把容器内的一切内容当作一段连续的纯文本字符串从而隐形化其中嵌套的交互元素。roletext主要用于 VoiceOver 特有的边缘场景它只应该应用在纯静态文本容器上。WAI-ARIA 1.2 规范明确指出一旦容器内出现交互内容这种子树展平subtree flattening行为就会变得危险。这条规则对应的 Skill 文档为 skills/aria-text/SKILL.md详细实现说明与代码示例见 skills/aria-text/references/rule.md。仓库中的规则源 aria-text.mdx 是 Skill 文档的上游数据二者内容一一对应。为什么文本展平会成为无障碍黑洞当屏幕阅读器遇到roletext容器时它会将整个子树合并为一个文本节点朗读。这意味着交互可见性Interactive Visibility容器内的链接、按钮等交互元素无法被屏幕阅读器用户聚焦和激活。用户虽然能在视觉上看到它们但在读屏环境中它们完全不存在。语义展平Semantic Flattening整个容器被拍平成单一字符串子元素原有的语义如link、button角色全部丢失。用户困惑User Confusion视觉正常的用户看得到链接屏幕阅读器用户却看不见两种用户的体验出现割裂。键盘访问断裂Keyboard Access纯键盘用户或许仍然能用 Tab 键到达容器内的按钮但屏幕阅读器不会正确播报它形成焦点到了、播报缺失的割裂体验用户不知道当前焦点落在什么控件上。这种场景被形象地称为无障碍黑洞accessibility black holes——交互内容在辅助技术面前凭空消失。代码示例正确与错误的写法以下是 skills/aria-text/references/rule.md 中给出的完整示例!-- ✅ Correct: Simple text container -- div roletext spanPrice: /span span$10.00/span /div !-- ❌ Incorrect: Contains a focusable link -- div roletext Learn more at a href/detailsthis link/a /div !-- ❌ Incorrect: Contains a focusable button -- div roletext Submit your form button typesubmitSubmit/button /div正确的形态roletext容器只包裹纯静态文本如价格标签Price: $10.00这类由多个 span 拼接的文本片段。此时展平语义是无害的反而能保证读屏时数字与货币符号按预期连读。错误的形态一旦容器中出现a链接或button按钮这类可聚焦元素展平就会把它们的可交互语义吞掉。两个错误示例分别对应链接被藏匿和按钮被藏匿两种典型事故。修复手法根据规则文档修复只有两条路径移除roletext当容器需要承载交互子元素时直接去掉roletext让子元素恢复原生语义把交互元素移出容器如果确实需要某个文本容器保持roletext则将链接、按钮等交互元素挪到容器外部避免嵌套。修复的核心判断标准是roletext只容纳静态文本内容不允许出现任何可聚焦后代links、buttons、inputs 等。豁免场景原生优先不为 ARIA 而 ARIA规则文档明确列出了三条例外Exceptions提醒审查者避免机械判罚优先使用原生 HTML 语义能使用原生元素表达语义时就不要用 ARIA。很多看似 ARIA 失败的问题在把底层元素修正为原生语义后就自然消失了。缺失 ARIA 不一定是最高优先级发现如果某个控件本身已经语义破损、没有可访问名称或键盘无法访问那么缺少 ARIA 属性并不应该被当成最强的发现。不要为了满足规则而硬加 ARIA如果某个功能本应采用原生元素或更简单的交互模式就不应该用 ARIA 去凑数。这三条豁免共同指向一个原则ARIA 是修复语义的工具不是合规的遮羞布。审查时应先检查原生语义是否成立再判断 ARIA 是否必要。标准对齐规则要求实现与以下标准保持一致并且强调验证渲染后的实际体验而不只是源码本身WAI-ARIA 1.2无障碍富互联网应用规范即roletext语义的权威来源MDN ARIA 文档作为实现层面的参考。验证方法从自动化到人工复测规则文档提供了一套双层验证策略自动化检查在浏览器的无障碍树accessibility tree或无障碍面板中检查相关元素、角色和可访问名称运行axe或Lighthouse等自动化无障碍检查工具确认规则在渲染结果中成立。人工检查使用纯键盘导航测试受影响的 UI确认规则在真实渲染体验中成立如果该规则影响关键交互用屏幕阅读器重新走一遍代表性用户流程。这里尤其值得注意规则文档反复强调验证渲染后的体验而不仅是源码——因为roletext的展平行为是运行时的语义行为静态看代码可能不容易发现交互元素的丢失。仓库中的完整实现链路从 MDX 规则到 Agent Skill这条规则并不是孤立存在的它在仓库中经历了一条完整的规则源 → 生成脚本 → Skill 文档流水线理解这条链路对使用 Skill 的开发者与 AI Agent 都有帮助。上游规则源规则的权威数据源是 packages/content/rules/en/accessibility/aria-text.mdx。该文件的 frontmatter 除基本信息外还定义了结构化字段包括whyItMatters规则的重要性说明即文本展平会隐藏交互元素tldr三条速查要点promptscheck/fix/explain/codeReview四个面向 Agent 的提示词aiContextAgent 使用场景提示sources规范来源WAI-ARIA 1.2 为主规范、MDN 为参考relatedRules关联规则清单包括aria-hidden-focus、aria-command-name、aria-required-children、aria-treeitem-name原因均为同属 accessibility/aria 区域通常一起审查。生成脚本scripts/generate/generate-skills.ts 负责把每个规则的 MDX frontmatter 生成到skills/{slug}/目录下SKILL.md由name、description、metadata与 Check / Fix / Explain / Code Review 四类提示词组装而成对应 buildSkillMdreferences/rule.md规则正文经 MDX 语法剥离后转为纯 Markdown对应 buildReferencesMd 与 stripMdxToMarkdown。从生成逻辑可以看出两个面向 Agent 的工程细节description 必须满足 Use when 前缀约定生成器会检查aiContext或description是否以 Use when 开头见 buildSkillMd这是为了 skill 框架做 Agent 意图匹配。这就是 SKILL.md 中 description 以 Use when reviewing rendered HTML... 开头的原因description 最短长度约束若不足 50 个字符生成器会自动拼接规则标题补足见 buildSkillMd。生成方式支持全量与增量两种pnpm generate:skills生成全部规则也可传入指定 MDX 文件路径由 lefthook 在提交时调用只重建变更的规则。安装与使用Skill 可独立安装# 安装全部 skills npx skills add frontendchecklist/skills # 只安装 aria-text 这一个 skill npx skills add frontendchecklist/skills --skill aria-text与 MCP 审计流程的衔接在聚合型 Skill skills/frontend-checklist-global/SKILL.md 中规则审查被编排进 MCP 工具工作流先用review_code审查粘贴的代码或单个文件、用audit_url审计公开页面再用search_rules、get_rule、fix_rule、explain_rule等工具实现见 packages/mcp/src/tools对具体问题给出精准修复建议。该 Skill 同时内置了保守的审查立场——只报告有直接代码证据支撑的问题而不是罗列所有可能的增强项这与本文规则的豁免场景精神一脉相承。面向 Agent 的四个操作提示词skills/aria-text/SKILL.md 为 AI Agent 定义了四步操作指引开发者和 Agent 均可直接复用操作提示词要点Check检查识别带roletext的元素确认其内部没有按钮、链接、输入框等可聚焦元素Fix修复从包含交互子元素的容器上移除roletext或将交互元素移到容器外部Explain解释说明roletext如何覆盖后代元素语义使交互组件对读屏用户不可访问Code Review代码审查审查渲染后的标记与交互状态精确定位违规的元素、角色、标签、焦点行为或键盘交互并说明如何用浏览器无障碍工具或辅助技术验证修复配合 skills/aria-text/references/rule.md 中的完整代码示例、豁免场景与双层验证方法这条 Skill 可以作为一次完整、可执行的无障碍审计的最小单元。小结roletext是一把双刃剑在纯文本容器上它能改善读屏连读体验一旦嵌套交互元素就会制造视觉可见、读屏不可达的黑洞。掌握 Front-End Checklist 的aria-text规则意味着你既能准确判罚可聚焦后代不可嵌套又能理性豁免原生语义优先、不为 ARIA 而 ARIA还能完成从自动化工具到人工复测的闭环验证。在仓库中这条规则以 aria-text.mdx 为数据源、以 SKILL.md 为 Agent 执行接口是理解整个 Front-End Checklist 规则体系如何从人类清单转化为机器可执行技能的绝佳样本。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Front-End Checklist 无障碍规则实战：修复 `role=“text“` 容器中的可聚焦子元素
Front-End Checklist 无障碍规则实战修复roletext容器中的可聚焦子元素【免费下载链接】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 仓库中的aria-text无障碍规则展开系统讲解为什么roletext容器内不应包含链接、按钮、输入框等可聚焦元素以及如何在代码审查与前端审计中快速定位、修复并用浏览器无障碍工具验证此类问题。读完本文你将掌握该规则的判定标准、修复手法、豁免场景以及它在仓库中从 MDX 规则源到 Agent Skill 的完整实现链路可直接用于日常开发与 AI 驱动的代码审查。规则定位一条关于语义展平的无障碍规则aria-text规则的全称是Avoid focusable descendants in roletext elements避免roletext元素包含可聚焦后代在仓库中的元数据定义如下见 packages/content/rules/en/accessibility/aria-text.mdx分类accessibility无障碍子类aria优先级medium中等难度intermediate进阶预计耗时10 分钟规则的核心原理一句话可以概括给容器加上roletext会强制屏幕阅读器把容器内的一切内容当作一段连续的纯文本字符串从而隐形化其中嵌套的交互元素。roletext主要用于 VoiceOver 特有的边缘场景它只应该应用在纯静态文本容器上。WAI-ARIA 1.2 规范明确指出一旦容器内出现交互内容这种子树展平subtree flattening行为就会变得危险。这条规则对应的 Skill 文档为 skills/aria-text/SKILL.md详细实现说明与代码示例见 skills/aria-text/references/rule.md。仓库中的规则源 aria-text.mdx 是 Skill 文档的上游数据二者内容一一对应。为什么文本展平会成为无障碍黑洞当屏幕阅读器遇到roletext容器时它会将整个子树合并为一个文本节点朗读。这意味着交互可见性Interactive Visibility容器内的链接、按钮等交互元素无法被屏幕阅读器用户聚焦和激活。用户虽然能在视觉上看到它们但在读屏环境中它们完全不存在。语义展平Semantic Flattening整个容器被拍平成单一字符串子元素原有的语义如link、button角色全部丢失。用户困惑User Confusion视觉正常的用户看得到链接屏幕阅读器用户却看不见两种用户的体验出现割裂。键盘访问断裂Keyboard Access纯键盘用户或许仍然能用 Tab 键到达容器内的按钮但屏幕阅读器不会正确播报它形成焦点到了、播报缺失的割裂体验用户不知道当前焦点落在什么控件上。这种场景被形象地称为无障碍黑洞accessibility black holes——交互内容在辅助技术面前凭空消失。代码示例正确与错误的写法以下是 skills/aria-text/references/rule.md 中给出的完整示例!-- ✅ Correct: Simple text container -- div roletext spanPrice: /span span$10.00/span /div !-- ❌ Incorrect: Contains a focusable link -- div roletext Learn more at a href/detailsthis link/a /div !-- ❌ Incorrect: Contains a focusable button -- div roletext Submit your form button typesubmitSubmit/button /div正确的形态roletext容器只包裹纯静态文本如价格标签Price: $10.00这类由多个 span 拼接的文本片段。此时展平语义是无害的反而能保证读屏时数字与货币符号按预期连读。错误的形态一旦容器中出现a链接或button按钮这类可聚焦元素展平就会把它们的可交互语义吞掉。两个错误示例分别对应链接被藏匿和按钮被藏匿两种典型事故。修复手法根据规则文档修复只有两条路径移除roletext当容器需要承载交互子元素时直接去掉roletext让子元素恢复原生语义把交互元素移出容器如果确实需要某个文本容器保持roletext则将链接、按钮等交互元素挪到容器外部避免嵌套。修复的核心判断标准是roletext只容纳静态文本内容不允许出现任何可聚焦后代links、buttons、inputs 等。豁免场景原生优先不为 ARIA 而 ARIA规则文档明确列出了三条例外Exceptions提醒审查者避免机械判罚优先使用原生 HTML 语义能使用原生元素表达语义时就不要用 ARIA。很多看似 ARIA 失败的问题在把底层元素修正为原生语义后就自然消失了。缺失 ARIA 不一定是最高优先级发现如果某个控件本身已经语义破损、没有可访问名称或键盘无法访问那么缺少 ARIA 属性并不应该被当成最强的发现。不要为了满足规则而硬加 ARIA如果某个功能本应采用原生元素或更简单的交互模式就不应该用 ARIA 去凑数。这三条豁免共同指向一个原则ARIA 是修复语义的工具不是合规的遮羞布。审查时应先检查原生语义是否成立再判断 ARIA 是否必要。标准对齐规则要求实现与以下标准保持一致并且强调验证渲染后的实际体验而不只是源码本身WAI-ARIA 1.2无障碍富互联网应用规范即roletext语义的权威来源MDN ARIA 文档作为实现层面的参考。验证方法从自动化到人工复测规则文档提供了一套双层验证策略自动化检查在浏览器的无障碍树accessibility tree或无障碍面板中检查相关元素、角色和可访问名称运行axe或Lighthouse等自动化无障碍检查工具确认规则在渲染结果中成立。人工检查使用纯键盘导航测试受影响的 UI确认规则在真实渲染体验中成立如果该规则影响关键交互用屏幕阅读器重新走一遍代表性用户流程。这里尤其值得注意规则文档反复强调验证渲染后的体验而不仅是源码——因为roletext的展平行为是运行时的语义行为静态看代码可能不容易发现交互元素的丢失。仓库中的完整实现链路从 MDX 规则到 Agent Skill这条规则并不是孤立存在的它在仓库中经历了一条完整的规则源 → 生成脚本 → Skill 文档流水线理解这条链路对使用 Skill 的开发者与 AI Agent 都有帮助。上游规则源规则的权威数据源是 packages/content/rules/en/accessibility/aria-text.mdx。该文件的 frontmatter 除基本信息外还定义了结构化字段包括whyItMatters规则的重要性说明即文本展平会隐藏交互元素tldr三条速查要点promptscheck/fix/explain/codeReview四个面向 Agent 的提示词aiContextAgent 使用场景提示sources规范来源WAI-ARIA 1.2 为主规范、MDN 为参考relatedRules关联规则清单包括aria-hidden-focus、aria-command-name、aria-required-children、aria-treeitem-name原因均为同属 accessibility/aria 区域通常一起审查。生成脚本scripts/generate/generate-skills.ts 负责把每个规则的 MDX frontmatter 生成到skills/{slug}/目录下SKILL.md由name、description、metadata与 Check / Fix / Explain / Code Review 四类提示词组装而成对应 buildSkillMdreferences/rule.md规则正文经 MDX 语法剥离后转为纯 Markdown对应 buildReferencesMd 与 stripMdxToMarkdown。从生成逻辑可以看出两个面向 Agent 的工程细节description 必须满足 Use when 前缀约定生成器会检查aiContext或description是否以 Use when 开头见 buildSkillMd这是为了 skill 框架做 Agent 意图匹配。这就是 SKILL.md 中 description 以 Use when reviewing rendered HTML... 开头的原因description 最短长度约束若不足 50 个字符生成器会自动拼接规则标题补足见 buildSkillMd。生成方式支持全量与增量两种pnpm generate:skills生成全部规则也可传入指定 MDX 文件路径由 lefthook 在提交时调用只重建变更的规则。安装与使用Skill 可独立安装# 安装全部 skills npx skills add frontendchecklist/skills # 只安装 aria-text 这一个 skill npx skills add frontendchecklist/skills --skill aria-text与 MCP 审计流程的衔接在聚合型 Skill skills/frontend-checklist-global/SKILL.md 中规则审查被编排进 MCP 工具工作流先用review_code审查粘贴的代码或单个文件、用audit_url审计公开页面再用search_rules、get_rule、fix_rule、explain_rule等工具实现见 packages/mcp/src/tools对具体问题给出精准修复建议。该 Skill 同时内置了保守的审查立场——只报告有直接代码证据支撑的问题而不是罗列所有可能的增强项这与本文规则的豁免场景精神一脉相承。面向 Agent 的四个操作提示词skills/aria-text/SKILL.md 为 AI Agent 定义了四步操作指引开发者和 Agent 均可直接复用操作提示词要点Check检查识别带roletext的元素确认其内部没有按钮、链接、输入框等可聚焦元素Fix修复从包含交互子元素的容器上移除roletext或将交互元素移到容器外部Explain解释说明roletext如何覆盖后代元素语义使交互组件对读屏用户不可访问Code Review代码审查审查渲染后的标记与交互状态精确定位违规的元素、角色、标签、焦点行为或键盘交互并说明如何用浏览器无障碍工具或辅助技术验证修复配合 skills/aria-text/references/rule.md 中的完整代码示例、豁免场景与双层验证方法这条 Skill 可以作为一次完整、可执行的无障碍审计的最小单元。小结roletext是一把双刃剑在纯文本容器上它能改善读屏连读体验一旦嵌套交互元素就会制造视觉可见、读屏不可达的黑洞。掌握 Front-End Checklist 的aria-text规则意味着你既能准确判罚可聚焦后代不可嵌套又能理性豁免原生语义优先、不为 ARIA 而 ARIA还能完成从自动化工具到人工复测的闭环验证。在仓库中这条规则以 aria-text.mdx 为数据源、以 SKILL.md 为 Agent 执行接口是理解整个 Front-End Checklist 规则体系如何从人类清单转化为机器可执行技能的绝佳样本。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考