better-accessibility

随创作而来的无障碍体验

无障碍不是最后才加上的合规打勾项，而是界面创作的底线。只要使用平台提供的功能，大部分要求都无需额外付出：原生元素自带键盘支持，真实标签会自动播报，而可见焦点环只需一条 CSS 规则。构建或审查 UI 代码时，请遵循这些原则，并按照项目自身的惯用方式编写每项修复：沿用现有的样式系统，绝不再并用另一套系统。

审查时，先只用键盘操作界面（每个流程都必须能在不使用鼠标的情况下完成），然后再以屏幕阅读器用户的视角检查：每个控件是否都会播报名称、角色和状态？不确定时，优先采用平台默认行为，而不是自定义重做；与其添加 ARIA，不如移除 ARIA。

渲染后元素配对的对比度测量和颜色修正见 better-colors 技能；视觉文本尺寸和 iOS 输入框缩放见 better-typography；空间布局 RTL 见 better-layout。

快速参考

类别	适用场景
焦点与键盘	焦点环、跳过链接、tabindex、焦点陷阱、APG 键盘模式
语义与 ARIA	优先使用原生元素、按钮与链接的区别、地标、无障碍名称、禁用状态
表单	标签、自动补全、错误消息、输入类型
屏幕阅读器	视觉隐藏内容、实时区域、提示、替代文本、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"（以编程方式设置焦点），绝不使用正值，因为正值会破坏自然顺序。复合控件使用 roving tabindex：当前激活项为 0，其他项均为 -1。

4. 限制并恢复焦点

模态框应在背景内容上设置 inert，打开时将焦点移入模态框，关闭时将焦点还给触发控件。添加 overscroll-behavior: contain，避免背景内容滚动。

5. 最小点击区域

WCAG 2.5.8 的 AA 级基准要求目标尺寸为 24×24 CSS 像素，或符合其定义的间距、等效控件、行内、用户代理或必要性例外。为便于操作，在触控场景中尽量达到 44×44px，在桌面界面中尽量达到 40×40px（密度允许时）。如果可见元素需要保持较小，可使用伪元素扩展点击区域。绝不要让扩展后的点击区域互相重叠，并为装饰层设置 pointer-events: none，避免光晕或渐变遮挡本应落在其下方控件上的点击。

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="Search"，而不是 alt="magnifying glass"。

13. 结构就是导航

使用能够描述各自章节并构成连贯大纲的标题；每页一个 <h1> 并正确嵌套标题层级是建议的默认做法，而不是 WCAG 通过或不通过的独立规则。提供一个可见的主 <main> 地标。如果重复的导航或页面框架位于其前面，应将“跳转到内容”链接设为第一个可聚焦元素。带锚点的标题应设置 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
重复的礼貌提示未被一致地播报	保留稳定的空状态区域并更新其文本；在目标屏幕阅读器上进行测试
为常规提示使用 assertive 实时区域	使用 polite；assertive 仅用于错误
在可聚焦元素上设置 aria-hidden="true"	移除该属性，或使元素不可聚焦
功能性图标的 alt 文本描述图片	描述操作：使用 alt="Search"，而不是 alt="magnifying glass"
表单有效之前禁用提交按钮	保持按钮启用；在提交时验证，并将焦点移至第一个错误处
装饰性光效或渐变层拦截点击	在该层设置 pointer-events: none，并添加 aria-hidden="true"
触摸后悬停样式仍然保持	使用 @media (hover: hover) 限定悬停样式
为原生 disabled 控件添加工具提示	在其旁显示常驻文本，或使用 aria-disabled 使其保持可聚焦

报告

独立的无障碍审查在所有已确认的问题均按照 review-output.md 中的格式报告，并附有验证结果和结论后，即告完成。在 better-interface 下，应以其格式为准。