Front-End-Checklist 无障碍指南彻底解决 aria-hidden 容器内的焦点幽灵问题Ghost Focus【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist当开发者为装饰性容器加上aria-hiddentrue却忘记处理其中的可交互元素时键盘用户会陷入一种诡异体验Tab 焦点消失在无声区域里屏幕阅读器一言不发用户完全不知道焦点在哪里、能操作什么。本文以 Front-End-Checklist 仓库中的aria-hidden-focus无障碍规则为核心系统讲解从可访问性树中隐藏元素 ≠ 从键盘 Tab 序中移除元素这一 WAI-ARIA 1.2 关键语义并给出tabindex-1与inert两种修复方案、自动化与手动验证流程以及仓库中真实代码的佐证。读完你将能写出既对视觉隐藏、又对键盘与辅助技术一致可用的组件。规则核心aria-hidden只影响可访问性树不影响 Tab 序规则文档 SKILL.md 与其完整实现说明 references/rule.md同规则还以 MDX 形式维护在 packages/content/rules/en/accessibility/aria-hidden-focus.mdx开篇即点明一个极易被忽略的事实当元素被标记为aria-hiddentrue时它被从可访问性树accessibility tree中移除但不会从键盘 Tab 顺序中移除。这是 WAI-ARIA 1.2 一起出现——后者聚焦模态框开关、SPA 导航、动态更新时焦点如何迁移而aria-hidden-focus聚焦被隐藏容器内是否还残留可聚焦子孙。在 Front-End-Checklist 的内容体系中该规则属于accessibility分类下的aria子类元数据标定为优先级 medium、难度 intermediate、预计检查耗时 10 分钟。Quick Reference三条必须记住的结论带有aria-hiddentrue的元素不得包含可聚焦的子孙元素链接、按钮、输入框等聚焦到隐藏元素会产生屏幕阅读器用户眼中的幽灵焦点ghost focus使用tabindex-1或inert属性来正确隐藏交互元素Check如何快速定位违规在审查渲染后的 HTML 时扫描所有aria-hiddentrue容器检查其中是否包含可聚焦元素——典型的有a链接button按钮input、select、textarea表单控件带tabindex的自定义组件仓库中的 MCP 审计工具 packages/mcp/src/tools/review-code.ts 展示了这类检查的代码级实现思路工具会对渲染出的代码做正则/字符串扫描例如在aria-hidden-body检查中直接匹配body[^]*aria-hidden\s*\s*[]true[]模式来标记把整页隐藏的违规写法对图片则要求要么rolepresentation要么aria-hiddentrue。可见扫描aria-hidden容器 → 检查其内部可交互性正是工程化审计工具的标准套路。Fix两种修复方案与完整代码示例规则给出了两种官方修复路径给可聚焦子元素添加tabindex-1把它从 Tab 序中移除但保留其可编程聚焦能力例如仍可通过脚本focus()适用于平时隐藏、必要时以编程方式聚焦的场景。在容器上使用inert属性让整个子树既不可聚焦也不可点击、同时从可访问性树中移除是最干净的现代方案。完整示例来自 references/rule.md!-- ✅ 正确可聚焦元素同时被移出 Tab 序 -- div aria-hiddentrue button tabindex-1Hidden Button/button /div !-- ✅ 正确使用 inert 属性现代浏览器支持 -- div inert buttonHidden Button/button /div !-- ❌ 错误对 AT 隐藏但可聚焦幽灵焦点 -- div aria-hiddentrue buttonI can be focused but not heard/button /div注意三种写法的差异错误示例中按钮仍留在 Tab 序里键盘用户 Tab 过去时屏幕阅读器完全沉默第一个正确示例用tabindex-1消解了这一矛盾第二个正确示例则让inert一次性处理容器内全部子孙。Why It Matters为什么这是真正的可用性灾难避免幽灵焦点阻止键盘焦点落入沉默区——那里没有任何信息被播报。用户清晰度保证每个可聚焦元素都有对应的屏幕阅读器播报维护用户对界面的掌控感。逻辑流畅性为纯键盘用户维持一致、可预测的导航路径。减少挫败感杜绝用户误以为浏览器或网站崩溃的情形——焦点凭空消失是常见的误判来源。Exceptions什么时候不该机械套用规则优先使用原生 HTML 语义而非 ARIA很多看似 ARIA 的问题在修正底层元素后自然消失。如果控件本身已经语义损坏、没有可访问名称或键盘不可达缺失某个 ARIA 属性不一定是最强的发现点。不要为了满足规则而堆砌 ARIA——如果该功能本应使用原生元素或更简单的交互模式实现应该重写功能而不是加属性。这些例外条款说明该规则是启发式而非教条先修语义再谈属性。Standards与规范对齐并验证渲染结果与 WAI-ARIA 1.2 对齐且必须验证渲染后的实际体验而非仅看源码。与 MDN: ARIA 对齐同样强调渲染态验证。这条验证渲染态的要求与仓库 review-code.ts 中对内联样式、焦点行为等按渲染后 HTML 做检查的设计哲学一脉相承。Support Notes浏览器兼容性与降级方案inert属性是最干净的现代修复但旧浏览器目标可能仍需要手动把子孙移出 Tab 序作为回退方案。必须在该项目目标浏览器中验证渲染后的焦点行为因为浏览器与辅助技术的组合在如何暴露隐藏内容上仍有差异。也就是说inert很好用但不能无脑依赖——先确认项目的浏览器支持矩阵例如仓库中 Next.js 应用的 package.json 声明的目标环境再决定是直接用inert还是写tabindex-1回退。Verification如何确认修复生效自动化检查检查浏览器无障碍树accessibility tree或无障碍面板中相关元素、角色、可访问名称是否消失。在适用处运行自动化无障碍检查器如 axe 或 Lighthouse。仓库中就有可落地的自动化载体MCP 工具集 packages/mcp/src/tools/review-code.ts 与check-rule工具可以把检测aria-hidden容器内的违规内容写成可重复执行的审计步骤而 packages/content/rules/en/accessibility/aria-hidden-focus.mdx 的 frontmatter 中还挂载了 axe DevTools 资源可直接用于人工审计流程。手动检查用纯键盘导航测试受影响的 UI确认规则在渲染体验中成立——从页面顶部反复按 Tab观察焦点是否进入任何视觉上不存在或屏幕阅读器不播报的区域。如果该规则影响关键交互用屏幕阅读器重测一条代表性用户流程。仓库实践佐证正确使用aria-hidden的真实案例浏览 apps/web/components 下的组件可以发现大量正确实践的样例——对纯装饰性图标使用aria-hiddentrue以避免它们干扰可访问名称例如creator-projects.tsx多个品牌图标ExternalLink、GitHubBrandIcon、Star均标记aria-hiddentrue因为它们是旁边文本链接/按钮的视觉装饰不需要进入可访问性树同时它们本身不可聚焦因此不会产生幽灵焦点。auth-button.tsx加载指示器Loader2、外部链接图标、用户图标等大量使用aria-hiddentrue。这些案例恰好示范了规则的适用边界对非交互的纯装饰元素使用aria-hiddentrue是安全的只有aria-hidden容器内还藏着可聚焦元素才是违规。如果这些图标被包在aria-hiddentrue容器里且图标本身或容器内其他子元素可聚焦就会触发本规则。在项目工作流中应用这条规则Front-End-Checklist 把规则同时维护在两条链路中内容/审计链路MDX 规则文件 packages/content/rules/en/accessibility/aria-hidden-focus.mdx 定义元数据优先级、难度、耗时、TLDR、检查/修复提示词、源码引用供前端清单站点与生成文档使用。Agent/技能链路skills/aria-hidden-focus/SKILL.md 以可被 Agent 消费的格式包装同一规则包含description何时使用、Check/Fix/Explain/Code Review四段式提示词并指向 references/rule.md 获取完整实现细节。实践中建议把该检查嵌入代码评审流程在审查任何隐藏区域折叠面板、轮播、离屏菜单、模态框关闭后的残留内容时先问三个问题——这个容器为什么对辅助技术隐藏里面有没有可聚焦元素Tab 过去后屏幕阅读器会播报什么三个问题都过关幽灵焦点就无处遁形。【免费下载链接】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 无障碍指南彻底解决 aria-hidden 容器内的焦点幽灵问题Ghost Focus【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist当开发者为装饰性容器加上aria-hiddentrue却忘记处理其中的可交互元素时键盘用户会陷入一种诡异体验Tab 焦点消失在无声区域里屏幕阅读器一言不发用户完全不知道焦点在哪里、能操作什么。本文以 Front-End-Checklist 仓库中的aria-hidden-focus无障碍规则为核心系统讲解从可访问性树中隐藏元素 ≠ 从键盘 Tab 序中移除元素这一 WAI-ARIA 1.2 关键语义并给出tabindex-1与inert两种修复方案、自动化与手动验证流程以及仓库中真实代码的佐证。读完你将能写出既对视觉隐藏、又对键盘与辅助技术一致可用的组件。规则核心aria-hidden只影响可访问性树不影响 Tab 序规则文档 SKILL.md 与其完整实现说明 references/rule.md同规则还以 MDX 形式维护在 packages/content/rules/en/accessibility/aria-hidden-focus.mdx开篇即点明一个极易被忽略的事实当元素被标记为aria-hiddentrue时它被从可访问性树accessibility tree中移除但不会从键盘 Tab 顺序中移除。这是 WAI-ARIA 1.2 一起出现——后者聚焦模态框开关、SPA 导航、动态更新时焦点如何迁移而aria-hidden-focus聚焦被隐藏容器内是否还残留可聚焦子孙。在 Front-End-Checklist 的内容体系中该规则属于accessibility分类下的aria子类元数据标定为优先级 medium、难度 intermediate、预计检查耗时 10 分钟。Quick Reference三条必须记住的结论带有aria-hiddentrue的元素不得包含可聚焦的子孙元素链接、按钮、输入框等聚焦到隐藏元素会产生屏幕阅读器用户眼中的幽灵焦点ghost focus使用tabindex-1或inert属性来正确隐藏交互元素Check如何快速定位违规在审查渲染后的 HTML 时扫描所有aria-hiddentrue容器检查其中是否包含可聚焦元素——典型的有a链接button按钮input、select、textarea表单控件带tabindex的自定义组件仓库中的 MCP 审计工具 packages/mcp/src/tools/review-code.ts 展示了这类检查的代码级实现思路工具会对渲染出的代码做正则/字符串扫描例如在aria-hidden-body检查中直接匹配body[^]*aria-hidden\s*\s*[]true[]模式来标记把整页隐藏的违规写法对图片则要求要么rolepresentation要么aria-hiddentrue。可见扫描aria-hidden容器 → 检查其内部可交互性正是工程化审计工具的标准套路。Fix两种修复方案与完整代码示例规则给出了两种官方修复路径给可聚焦子元素添加tabindex-1把它从 Tab 序中移除但保留其可编程聚焦能力例如仍可通过脚本focus()适用于平时隐藏、必要时以编程方式聚焦的场景。在容器上使用inert属性让整个子树既不可聚焦也不可点击、同时从可访问性树中移除是最干净的现代方案。完整示例来自 references/rule.md!-- ✅ 正确可聚焦元素同时被移出 Tab 序 -- div aria-hiddentrue button tabindex-1Hidden Button/button /div !-- ✅ 正确使用 inert 属性现代浏览器支持 -- div inert buttonHidden Button/button /div !-- ❌ 错误对 AT 隐藏但可聚焦幽灵焦点 -- div aria-hiddentrue buttonI can be focused but not heard/button /div注意三种写法的差异错误示例中按钮仍留在 Tab 序里键盘用户 Tab 过去时屏幕阅读器完全沉默第一个正确示例用tabindex-1消解了这一矛盾第二个正确示例则让inert一次性处理容器内全部子孙。Why It Matters为什么这是真正的可用性灾难避免幽灵焦点阻止键盘焦点落入沉默区——那里没有任何信息被播报。用户清晰度保证每个可聚焦元素都有对应的屏幕阅读器播报维护用户对界面的掌控感。逻辑流畅性为纯键盘用户维持一致、可预测的导航路径。减少挫败感杜绝用户误以为浏览器或网站崩溃的情形——焦点凭空消失是常见的误判来源。Exceptions什么时候不该机械套用规则优先使用原生 HTML 语义而非 ARIA很多看似 ARIA 的问题在修正底层元素后自然消失。如果控件本身已经语义损坏、没有可访问名称或键盘不可达缺失某个 ARIA 属性不一定是最强的发现点。不要为了满足规则而堆砌 ARIA——如果该功能本应使用原生元素或更简单的交互模式实现应该重写功能而不是加属性。这些例外条款说明该规则是启发式而非教条先修语义再谈属性。Standards与规范对齐并验证渲染结果与 WAI-ARIA 1.2 对齐且必须验证渲染后的实际体验而非仅看源码。与 MDN: ARIA 对齐同样强调渲染态验证。这条验证渲染态的要求与仓库 review-code.ts 中对内联样式、焦点行为等按渲染后 HTML 做检查的设计哲学一脉相承。Support Notes浏览器兼容性与降级方案inert属性是最干净的现代修复但旧浏览器目标可能仍需要手动把子孙移出 Tab 序作为回退方案。必须在该项目目标浏览器中验证渲染后的焦点行为因为浏览器与辅助技术的组合在如何暴露隐藏内容上仍有差异。也就是说inert很好用但不能无脑依赖——先确认项目的浏览器支持矩阵例如仓库中 Next.js 应用的 package.json 声明的目标环境再决定是直接用inert还是写tabindex-1回退。Verification如何确认修复生效自动化检查检查浏览器无障碍树accessibility tree或无障碍面板中相关元素、角色、可访问名称是否消失。在适用处运行自动化无障碍检查器如 axe 或 Lighthouse。仓库中就有可落地的自动化载体MCP 工具集 packages/mcp/src/tools/review-code.ts 与check-rule工具可以把检测aria-hidden容器内的违规内容写成可重复执行的审计步骤而 packages/content/rules/en/accessibility/aria-hidden-focus.mdx 的 frontmatter 中还挂载了 axe DevTools 资源可直接用于人工审计流程。手动检查用纯键盘导航测试受影响的 UI确认规则在渲染体验中成立——从页面顶部反复按 Tab观察焦点是否进入任何视觉上不存在或屏幕阅读器不播报的区域。如果该规则影响关键交互用屏幕阅读器重测一条代表性用户流程。仓库实践佐证正确使用aria-hidden的真实案例浏览 apps/web/components 下的组件可以发现大量正确实践的样例——对纯装饰性图标使用aria-hiddentrue以避免它们干扰可访问名称例如creator-projects.tsx多个品牌图标ExternalLink、GitHubBrandIcon、Star均标记aria-hiddentrue因为它们是旁边文本链接/按钮的视觉装饰不需要进入可访问性树同时它们本身不可聚焦因此不会产生幽灵焦点。auth-button.tsx加载指示器Loader2、外部链接图标、用户图标等大量使用aria-hiddentrue。这些案例恰好示范了规则的适用边界对非交互的纯装饰元素使用aria-hiddentrue是安全的只有aria-hidden容器内还藏着可聚焦元素才是违规。如果这些图标被包在aria-hiddentrue容器里且图标本身或容器内其他子元素可聚焦就会触发本规则。在项目工作流中应用这条规则Front-End-Checklist 把规则同时维护在两条链路中内容/审计链路MDX 规则文件 packages/content/rules/en/accessibility/aria-hidden-focus.mdx 定义元数据优先级、难度、耗时、TLDR、检查/修复提示词、源码引用供前端清单站点与生成文档使用。Agent/技能链路skills/aria-hidden-focus/SKILL.md 以可被 Agent 消费的格式包装同一规则包含description何时使用、Check/Fix/Explain/Code Review四段式提示词并指向 references/rule.md 获取完整实现细节。实践中建议把该检查嵌入代码评审流程在审查任何隐藏区域折叠面板、轮播、离屏菜单、模态框关闭后的残留内容时先问三个问题——这个容器为什么对辅助技术隐藏里面有没有可聚焦元素Tab 过去后屏幕阅读器会播报什么三个问题都过关幽灵焦点就无处遁形。【免费下载链接】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），仅供参考
