用途:这是一份无障碍(a11y)审查清单,用于审查 React/Next.js 中基于 Radix UI / shadcn/ui 构建的组件改动。其前提是这些库已自动处理键盘导航、焦点管理与 ARIA,审查重点在于发现对库的误用,而非缺少手写实现;不确定时降低置信度而非断言。
主要能力与检查项:
- 组件库误用:Dialog/Sheet 缺少 DialogTitle(可用 VisuallyHidden 包裹,或在 DialogContent 上加 aria-label);AlertDialog 缺少 Description(须显式 aria-describedby={undefined} 退出);Select/Combobox 触发器无可访问标签;仅图标的 DropdownMenuItem 缺少文本或 aria-label;Tooltip 作为唯一可访问名称;以及用 onKeyDown 里 preventDefault/stopPropagation 覆盖 Radix 键盘处理。
- 表单与标签:每个输入须有可访问名称(FormLabel、label htmlFor、aria-label、aria-labelledby),placeholder 不算标签;错误信息须与输入关联(FormMessage 自动关联,否则需手动 aria-describedby);必填项须用 aria-required 或原生 required 程序化标注;单选/复选组需用 RadioGroup 或 fieldset/legend 分组语义。
- 可访问名称:仅图标按钮与链接需 aria-label,sr-only 文本是等效替代;装饰性图标应 aria-hidden="true"。
- 语义 HTML 与回归防护:交互须用 button / a / Link,禁止 div onClick 或 span onClick;表格使用语义标签,复杂表格 th 宜加 scope;禁止 user-scalable=no 或 maximum-scale=1。
- 焦点管理:非 Radix Dialog 的自定义模态须移入焦点、困住焦点、关闭后归还焦点并支持 Escape;outline-none 必须配 focus-visible:ring-*;路由切换焦点移至主内容;禁止正 tabIndex。
- 动态内容与实时区域:Sonner toast 默认 role="status" + aria-live="polite",自定义通知需实时区域,关键错误宜 role="alert";加载状态用 aria-busy、sr-only 或 aria-live 告知;聊天流式消息应被播报;内联校验错误须关联或使用 aria-live。
- 特殊组件:Monaco 编辑器有已知无障碍局限,作为必填输入时考虑文本替代;React Flow 需提供键盘替代操作;带行操作的数据表须保证操作按钮可访问。
使用方式:对照改动组件逐节审查,并非每节都适用(表单检查只用于表单,模态检查只用于模态)。资料给出严重度校准:div/span onClick 与键盘陷阱为 CRITICAL,自定义模态无焦点管理等为 MAJOR,装饰图标缺 aria-hidden 等为 MINOR,复杂表格 th 缺 scope 为 INFO。
限制:清单面向特定代码库(Radix UI / shadcn/ui、react-hook-form + Zod、Sonner、Lucide 等),不具备通用工具的安装或运行方法;资料未提供许可证、价格、依赖安装命令或更新日期,这些暂未提供。