frontend-a11y

用途

frontend-a11y 是一套针对 React 与 Next.js 的无障碍（Accessibility）开发模式，用于在编写和代码审查阶段解决最常见的无障碍问题。资料指出，它覆盖代码审查中最高频被标记的几类问题：表单缺少标签、ARIA 使用错误、交互元素缺少语义、键盘导航失效。

适用时机

资料给出的适用场景包括：

构建或审查表单组件（input、select、textarea）
创建交互元素（模态框、下拉菜单、工具提示、标签页）
在 div 或 span 上使用 onClick
为任意元素添加 aria-* 属性
实现键盘导航或焦点管理
接收到代码审查工具（CodeRabbit、ESLint a11y）的无障碍反馈
构建必须支持屏幕阅读器的组件

主要能力

表单无障碍

重点处理 htmlFor 与 id 配对、必填字段标识、错误提示关联。示例中展示了正确做法：label 的 htmlFor 与 input 的 id 匹配；必填字段使用 required 与 aria-required="true"，并用 aria-hidden="true" 的星号避免屏幕阅读器误读；错误信息通过 aria-describedby 关联，配合 aria-invalid 与 role="alert"。资料还给出一个完整的可访问登录表单组件示例。

语义化 HTML

强调使用与意图匹配的元素。资料对比了错误与正确写法：不要在 div 上绑定 onClick 代替 button，不要用 div 模拟导航链接，不要跳级使用标题（h1 直接到 h4）。button 可获得焦点、支持 Enter/Space 激活，a 标签支持右键、中键与键盘导航。

ARIA 属性

资料明确提示：仅当原生 HTML 语义不足时才使用 ARIA，错误的 ARIA 比没有 ARIA 更糟。内容包括：aria-label（当没有可见标签文本时使用）与 aria-labelledby（存在可见标签文本时引用其他元素）的区别；aria-describedby 提供补充说明；aria-live 用于动态内容播报（polite 等待用户当前操作完成，assertive 立即打断，仅用于紧急错误），示例使用 role="status"、aria-live 与 aria-atomic；以及 aria-expanded 与 aria-controls 用于手风琴组件。

键盘导航

要求每个交互元素都能仅用键盘到达与操作。资料给出自定义下拉菜单的完整示例，处理 ArrowDown、ArrowUp、Enter、空格与 Escape 键，并使用 role="combobox"、aria-haspopup="listbox"、role="listbox"、role="option"、aria-selected 以及 tabIndex={0}。

焦点管理

强调 UI 状态变化时焦点应合理移动，尤其是模态框与路由切换。示例展示模态框打开时记录当前焦点元素并将焦点移入模态框，关闭时恢复焦点，并使用 role="dialog"、aria-modal="true"、aria-labelledby 以及 Escape 关闭。资料特别说明，该示例只覆盖初始焦点与恢复，完整的焦点陷阱（Tab/Shift+Tab 循环）建议使用 focus-trap-react 等库处理动态内容和嵌套 portal 等边界情况。

图像与图标

区分装饰性图片与有意义的图片：装饰性图片使用 alt="" 与 aria-hidden="true"；有意义的图片提供描述性 alt 文本；纯图标按钮使用 aria-label，图标本身用 aria-hidden="true"。

减少动效

提供 useReducedMotion 钩子示例，通过 window.matchMedia('(prefers-reduced-motion: reduce)') 检测系统设置，并在动画中据此关闭过渡效果。

反模式

资料列出的反模式包括：在非交互元素上使用 onClick 且无键盘支持；在没有 role 的 div 上使用 aria-label；用 placeholder 代替 label；使用正数 tabIndex 造成不可预测的 Tab 顺序；在可聚焦元素上使用 aria-hidden 导致键盘用户被困；在 div 上使用 role="button" 但缺少键盘处理（tabIndex={0}、Enter/Space 的 onKeyDown）。

使用方式

该技能以模式与代码示例形式提供，可在构建或审查组件时对照其 Checklist 逐项检查：每个 input/select/textarea 是否通过 htmlFor/id 连接 label；错误信息是否用 aria-describedby 关联并标记 role="alert"；div/span 上的 onClick 是否具备 role、tabIndex、onKeyDown；纯图标按钮是否有 aria-label；装饰性图片是否使用 alt="" 与 aria-hidden="true"；模态框关闭时是否恢复焦点（完整焦点陷阱建议使用 focus-trap-react 等库）；动态内容更新是否使用 aria-live；动画是否尊重 prefers-reduced-motion。

限制

资料未提供该技能的具体安装方式、收费信息、运行平台要求或性能数据，这些内容暂未提供。

技能介绍

用途