融入工艺的无障碍设计
无障碍并非事后强加的合规复选框,而是界面工艺的基石。如果善用平台特性,大部分无障碍功能都是免费的:原生元素自带键盘支持,真实标签能自行宣告,可视焦点环仅需一条CSS规则。在构建或审查UI代码时应用这些原则,并在应用修复时匹配项目现有的样式系统(Tailwind、普通CSS或CSS-in-JS)。
进行审查时,首先以纯键盘用户身份走查界面(每个流程必须在无需鼠标的情况下完成),然后以屏幕阅读器用户身份操作:每个控件是否宣告其名称、角色和状态?如有疑问,优先使用平台默认行为而非自定义重构,并且移除ARIA而非添加它。
渲染对比度的测量与颜色修复由 better-colors 技能负责;视觉文字大小和iOS输入缩放由 better-typography 处理;RTL空间布局则由 better-layout 处理。
快速参考
| 类别 | 适用场景 |
|---|---|
| 焦点与键盘 | 焦点环、跳转链接、tabindex、焦点陷阱、APG键盘模式 |
| 语义与ARIA | 优先使用原生元素、按钮与链接的区别、地标、可访问名称、禁用状态 |
| 表单 | 标签、自动填充、错误提示、输入类型 |
| 屏幕阅读器 | 视觉隐藏内容、实时区域、Toast、替代文本、SVG |
| 点击区域 | 目标大小、扩展点击区域、碰撞规则 |
| 动效与缩放 | prefers-reduced-motion、自动播放与定时UI、200%缩放、内容重排、rem与px |
核心原则
1. 优先使用原生元素
ARIA的第一条规则:当存在原生元素时,不要使用ARIA。用 <button> 表示操作,用 <a href> 表示导航(它必须支持Cmd/Ctrl/中键点击),永远不要用 <div onClick>。没有ARIA比错误的ARIA更好。
2. 可见的焦点环
样式化 :focus-visible,而非单纯的 :focus,这样键盘用户会看到焦点环,而鼠标用户通常不会。优先使用浏览器未修改的焦点指示器。如果设计需要自定义焦点环,请使用项目的焦点令牌或其他明确的颜色,并验证完整指示器与其经过的每个相邻颜色的对比;currentColor 仅在通过相同检查后才可接受。使用至少 2px 的实线轮廓或等效的可视区域。切勿在没有经过验证的替代方案的情况下使用 outline: none,并在强制颜色模式下保留系统颜色。
3. 完整的键盘支持
每个指针交互都需要对应的键盘路径,遵循ARIA APG模式:Escape键关闭覆盖层,方向键在复合控件(标签页、菜单、列表框)内移动,Tab键在控件之间移动,Enter和Space键激活。仅使用 tabindex="0"(加入自然Tab顺序)和 tabindex="-1"(编程焦点),永远不要使用正数值,否则会破坏自然顺序。复合控件使用罗盘式tabindex:活动项为 0,其他项为 -1。
4. 陷阱与恢复焦点
模态框在背景内容上设置 inert,打开时将焦点移入内部,关闭时将焦点返回到触发元素。添加 overscroll-behavior: contain 以防止背景内容滚动。
5. 最小点击区域
WCAG 2.5.8的AA级基准是24×24 CSS像素的目标或其定义的间距、等效控件、内联、用户代理或必要例外之一。为了更轻松激活,在触摸上下文中目标设定为44×44px,在密度允许的桌面界面中设定为40×40px。如果可见元素应保持较小尺寸,则使用伪元素扩展。切勿让扩展的点击区域重叠。
6. 为每个控件添加标签和类型
每个输入框都需要一个 <label for> 或包裹的 <label>;占位符永远不能替代标签,并且标签和控件共享一个点击目标:复选框及其文本之间没有死区。添加具有有意义 name 的 autocomplete,以及正确的 type 和 inputmode 以适配键盘。切勿阻止粘贴;用户会粘贴密码和一次性验证码。
7. 可宣告的错误信息
保持提交按钮启用直到请求开始,然后在请求期间禁用并用旋转图标替换,同时保留原始标签。在提交时进行验证:为失败的字段标记 aria-invalid="true",将 aria-describedby 指向内联错误文本,并将焦点放在第一个无效字段上。当原生控件确实不可用时,使用原生的 disabled。仅在有意保留可聚焦性或可发现性时使用 aria-disabled="true";此时需在代码中阻止指针、键盘和表单行为,并明确样式化状态。
8. 无处不在的可访问名称
仅图标的按钮需要描述性的 aria-label。可见标签文本必须出现在可访问名称中。装饰性元素应设置 aria-hidden="true",切勿放在可聚焦元素上。
9. 不要仅依赖颜色
状态需要冗余的提示:图标、文本或下划线伴随颜色。根据内容和状态确定适用的WCAG对比度要求,然后使用 better-colors 测量渲染的前景/背景对。当对比度失败时,报告该颜色对及其未满足的要求;除非被要求,否则不要更改项目的颜色。
10. 尊重 prefers-reduced-motion
将动效包裹在 @media (prefers-reduced-motion: no-preference) 中,使其为选择性加入。在减少动效模式下,用透明度淡入淡出替换滑动和缩放效果;完全删除视差滚动和自动播放。与此偏好无关:自动播放的媒体需要可见的暂停控件,承载操作或错误的Toast需保留直到用户关闭。
11. 宣布动态内容
对字段特定的验证使用 aria-describedby,对不绑定到控件的非紧急更新(如Toast或结果计数)使用礼貌的实时区域(role="status"),仅对不绑定到控件的紧急错误使用 role="alert"。为了可靠地重复宣布礼貌更新,在更新其文本之前渲染一个稳定的空区域;动态插入的警报具有不同的支持级别,必须针对目标屏幕阅读器进行测试。
12. 按用途编写替代文本
装饰性图像使用 alt="",信息性图像描述含义,功能性图像描述操作:搜索图标按钮的 alt="搜索",而不是 alt="放大镜"。
13. 结构即导航
使用描述其章节并形成连贯大纲的标题;一个页面级 <h1> 和正确嵌套的级别是推荐的默认值,而非独立的WCAG通过/失败规则。暴露一个可见的主要 <main> 地标。当重复导航或chrome元素在其之前时,使“跳转到主要内容”链接成为第一个可聚焦元素。锚定标题需设置 scroll-margin-top。
14. 在缩放和文本大小调整下正常工作
页面必须在200%缩放和320px宽度内容重排下正常工作,且无水平滚动。在文本容器上使用 min-height 代替固定的 height,在适合代码库约定的情况下优先使用 rem 断点,并保持视口meta标签不超过读者可缩放的程度。
常见错误
| 错误 | 修正 |
|---|---|
使用 outline: none 移除焦点环 | 改为样式化 :focus-visible;鼠标点击不会显示它 |
| 假设自定义焦点颜色在所有地方都有效 | 验证完整指示器与每个相邻颜色的对比,并在强制颜色模式下检查 |
使用 <div onClick> 作为按钮或链接 | 操作使用 <button>,导航使用 <a href> |
| 仅使用占位符作为标签 | 添加可见的 <label for>;占位符在输入时消失 |
使用正数的 tabindex 修复焦点顺序 | 修复DOM顺序;仅使用 0 和 -1 |
| 重复的礼貌更新宣布不一致 | 保持一个稳定的空状态区域并更新其文本;测试目标屏幕阅读器 |
对常规的Toast使用 assertive 实时区域 | 使用 polite;将 assertive 保留给错误 |
在可聚焦元素上设置 aria-hidden="true" | 移除它或使元素不可聚焦 |
| 功能性图标的alt描述图片 | 描述操作:alt="搜索",而不是 alt="放大镜" |
| 提交按钮在表单有效前处于禁用状态 | 保持其启用;在提交时验证并将焦点放在第一个错误上 |
审查输出格式
仅当用户要求独立的无障碍审查时使用此格式。当 better-interface 编排审查时,向该技能提供领域证据和发现,并让其输出格式、严重性等级、合并规则、上限和裁决优先。
以两部分形式呈现独立审查。
发现项
按原则分组所有确认的发现项。使用一个包含 严重性、位置、修改前、修改后 和 原因 列的Markdown表格。切勿使用单独的“修改前:”/“修改后:”行。
- 严重性:
高表示阻止任务、对辅助技术隐藏内容或导致系统性无障碍失败;中表示使交互明显更困难;低表示孤立的精细优化。 - 位置:注明
path/to/file:行号。如果工件没有源文件,则注明确切的屏幕和组件名称。 - 修改前/修改后:展示当前实现与可操作的替换方案。
- 原因:指出违反的原则及其对用户的影响。
将重复的系统性问题合并为一行,并列出所有受影响的位置。省略没有发现项的原则。
示例
无处不在的可访问名称
| 严重性 | 位置 | 修改前 | 修改后 | 原因 |
|---|---|---|---|---|
| 高 | src/Dialog.tsx:42 | <button><XIcon /></button> | 添加 aria-label="关闭";将图标标记为 aria-hidden="true" | 仅图标的控件没有可访问名称 |
| 高 | src/Nav.tsx:18 | <a href="/settings"><GearIcon /></a> | 添加 aria-label="设置" | 链接目标对屏幕阅读器不可用 |
可见的焦点环
| 严重性 | 位置 | 修改前 | 修改后 | 原因 |
|---|---|---|---|---|
| 高 | src/button.css:12 | button:focus { outline: none; } | button:focus-visible { outline: 2px solid; outline-offset: 2px; } | 键盘用户看不到焦点 |
| 高 | src/Menu.tsx:31 | focus:outline-none | focus-visible:outline-2 focus-visible:outline-offset-2 | 菜单导航没有可见的焦点指示器 |
可宣告的错误信息
| 严重性 | 位置 | 修改前 | 修改后 | 原因 |
|---|---|---|---|---|
| 高 | src/EmailField.tsx:27 | 错误仅通过 border-red-500 显示 | 添加 aria-invalid="true" + aria-describedby="email-error" 以及内联错误文本 | 仅靠颜色既无法解释也无法宣布错误 |
| 中 | src/SignupForm.tsx:64 | 提交按钮在表单有效前禁用 | 保持提交启用;失败时聚焦第一个无效字段 | 禁用操作隐藏了需要修复的内容 |
最小点击区域
| 严重性 | 位置 | 修改前 | 修改后 | 原因 |
|---|---|---|---|---|
| 中 | src/Toolbar.tsx:22 | size-4 仅图标按钮 | 使用 after:absolute after:size-11 将点击区域扩展到44×44px | 目标太小,无法可靠触摸输入 |
验证与裁决
在发现项之后:
- 验证:列出所执行的确切检查及其观察到的结果,包括键盘遍历、可访问名称检查以及适用的屏幕阅读器或自动化检查。如果某项检查未执行,则说明仍需验证的内容。
- 裁决:如果存在任何
高严重性发现项,则为阻止;如果仅存在中或低严重性发现项,则为需要更改;仅当没有可操作的发现项时,才为批准。
如果没有发现项,则省略表格,声明“无可操作的无障碍发现项”,报告验证结果,并以 批准 结束。