accessibility

无障碍访问

无障碍 Web 界面是法律、伦理和商业层面的强制要求。

适用范围

适用于以下场景：审核 HTML 结构与语义、设置 ARIA 属性、实现键盘导航、检查对比度、设计无障碍表单、提升媒体的无障碍性、确保符合 BFSG 要求，或审核现有界面的无障碍性。

原则

1. 无障碍是基本要求，而非特殊功能

无障碍设计让每个人都受益。情境限制（阳光直射、环境嘈杂、一只手被占用）会影响所有人。

2. 从一开始就做好，而非事后补救

事后补救的成本高出 10 倍，效果也差 10 倍。无障碍应贯穿每个阶段：构思、设计、开发和测试。

3. POUR 四项原则都是强制要求

可感知、可操作、可理解、稳健。

4. 技术与设计必须协同

无障碍不只是开发者（HTML）的责任，也不只是设计方面（对比度）的责任。两者必须协同配合。

5. 法律义务（BFSG 自 2025 年 6 月 28 日起生效）

德国《无障碍强化法》（BFSG）要求许多公司提供数字无障碍服务。这不是可选项。

规则

语义化 HTML

• 应做：根据用途使用原生元素：操作使用 <button>，导航使用 <a>，以及 <nav>、<main>、<article>。
• 应做：保持标题层级逻辑清晰：每页恰好使用一个 <h1>。不要跳过层级。
• 应做：使用地标元素：<header>、<nav>、<main>、<aside>、<footer>。
• 不要：将 <div> 或 <span> 用作交互元素。<div onclick> 不是按钮。
• 不要：将标题用于样式设置。

ARIA 属性

• 应做：仅在没有原生 HTML 元素能满足用途时使用 ARIA。
• 应做：为没有可见文本的交互元素（图标按钮）添加 aria-label。
• 应做：为动态内容（Toast 通知）使用 aria-live="polite"。
• 应做：为错误消息使用 role="alert"。
• 不要：在元素上过度使用 ARIA。冗余的 ARIA 会造成负面影响。
• 不要：对可见且可交互的元素设置 aria-hidden="true"。

键盘导航

• 应做：确保所有交互元素都能通过键盘操作（Tab、Enter、Space、Escape、方向键）。
• 应做：提供可见的焦点指示器：对比度至少为 3:1，轮廓为 2-3px。
• 应做：在模态框中实现焦点陷阱。
• 应做：将跳转到内容的链接设为第一个可聚焦元素。
• 应做：确保 Tab 顺序与视觉阅读顺序一致。tabindex 仅使用 0 或 -1。
• 不要：使用 tabindex > 0（会破坏自然顺序）。
• 不要：在没有充分替代方案的情况下设置 outline: none。

对比度与颜色

• 应做：普通文本：至少 4.5:1（WCAG AA）。
• 应做：大号文本（>= 24px / >= 18.66px 粗体）：至少 3:1。
• 应做：UI 组件：至少 3:1。
• 应做：绝不要仅用颜色传达信息。始终提供第二种提示：文本、图标或图案。
• 应做：测试色觉缺陷情况（Chrome DevTools > Rendering > Emulate vision deficiencies）。
• 不要：将红绿差异用于关键信息（8% 的男性用户会受到影响）。

图像与媒体

• 应做：信息性图像使用描述性 alt 文本（描述内容，而非外观）。
• 应做：装饰性图像使用 alt=""（空 alt 文本）。
• 应做：视频配字幕，音频配文字稿。
• 应做：动画应可暂停。在 CSS 中遵循 prefers-reduced-motion。
• 不要：使用闪烁内容（每秒闪烁超过 3 次可能引发癫痫）。

表单

• 应做：通过 for/id 将每个字段与可见的 <label> 关联。
• 应做：必填字段使用文本标记，并设置 aria-required="true"。
• 应做：在字段旁直接显示错误消息，并使用 aria-describedby。
• 应做：为标准字段使用 autocomplete 属性。
• 不要：用占位符替代标签。
• 不要：使用没有无障碍替代方案的 CAPTCHA。

响应式设计与触控

• DO：触控目标最小为 44x44px（WCAG），建议为 48x48px。
• DO：触控目标之间的间距至少为 8px。
• DO：支持放大至 200%，且不影响功能。
• DON'T：禁止缩放（user-scalable=no、maximum-scale=1）。

动效与动画

• DO：遵循 prefers-reduced-motion。减少或移除动画。
• DO：让自动播放的动效（轮播、视频）可以暂停。
• DON'T：使用视差或大幅动效时，不提供 prefers-reduced-motion 回退方案。

详细的模式说明和代码示例：请参阅 references/patterns.md

模式

跳过导航

第一个可聚焦链接：“跳转到内容”。默认视觉隐藏，聚焦时显示。链接指向 <main>。

无障碍模态框

使用 role="dialog" + aria-modal="true" + aria-labelledby。限制焦点范围。按 Escape 关闭。焦点返回触发元素。

错误摘要

在表单顶部显示错误摘要，并添加指向受影响字段的链接。使用 role="alert"。此外，还应显示行内错误。

无障碍手风琴

使用 <button> 作为触发元素，并设置 aria-expanded。内容使用 aria-labelledby。支持使用方向键导航。

反模式

Div 大杂烩

所有内容都用 <div> 和 <span> 构建。解决方案：使用原生 HTML 元素。

不可见的焦点指示器

使用 outline: none，但不提供替代样式。解决方案：提供可见的焦点样式，对比度至少为 3:1。

用占位符代替标签

字段没有 <label>。解决方案：始终使用可见标签。占位符仅作补充。

自动播放媒体

带声音自动播放。解决方案：仅在用户操作后开始播放。自动播放时只能静音，并提供暂停选项。

ARIA 过度使用

在 <button> 上设置 role="button"。解决方案：优先使用原生 HTML。仅在不得已时使用 ARIA。

阻止缩放

视口 meta 标签中设置 maximum-scale=1。解决方案：视口设置中不限制缩放。

检查清单

结构与语义

• 每个页面是否恰好有一个 <h1>？
• 标题层级是否连续无跳级？
• 是否包含地标元素？
• 是否包含“跳转到内容”链接？
• 是否没有可交互的 <div> / <span> 元素？

对比度与颜色

• 普通文本对比度是否至少为 4.5:1？
• 大号文本对比度是否至少为 3:1？
• UI 组件对比度是否至少为 3:1？
• 是否从不只用颜色作为唯一提示？
• 是否测试过色觉缺陷情况？

键盘与交互

• 是否所有内容都可通过键盘访问？
• 是否有可见的焦点指示器？
• 模态框中是否限制了焦点范围？
• Tab 顺序是否与视觉顺序一致？
• 是否没有 tabindex > 0？

图片与媒体

• 信息性图片是否有 alt 文本？
• 装饰性图片是否使用 alt=""？
• 视频是否有字幕？
• 是否遵循 prefers-reduced-motion？

表单

• 每个字段是否都有可见的 <label>？
• 必填字段是否有标记并设置了 aria-required？
• 行内错误是否使用了 aria-describedby？
• 是否没有用占位符代替标签？

移动端与响应式设计

• 触控目标是否至少为 44x44px？
• 是否可以放大至 200%？

法律要求

• 是否评估了 BFSG 的适用性？
• 是否将 WCAG 2.1 AA 作为最低标准？
• 是否提供了无障碍声明？

交叉引用

• ui-design -- 无障碍 UI 组件和状态
• web-typography -- 可读的字号和对比度要求
• color-theory -- WCAG 对比度要求、色觉缺陷
• usability -- 无障碍与易用性的交集
• responsive-design -- 触控目标、缩放、移动端屏幕阅读器
• navigation-design -- 键盘导航、跳过链接、地标