wcag-accessibility

WCAG 无障碍（EN 301 549 / 欧洲标准）

标准

**《欧洲无障碍法案》（EAA）**要求欧盟境内的数字产品和服务符合 EN 301 549，该标准引用 WCAG 2.2 AA 级作为技术基准。这不是可选项，而是在欧盟市场运营的产品必须满足的法律要求。

**默认始终遵循 WCAG 2.2 AA 标准进行构建。**如需偏离，必须提供明确且有记录的理由。不要因为工期压力或设计偏好而跳过无障碍要求。

WCAG 2.2 AA 将要求归纳为四项原则：可感知、可操作、可理解、健壮。

---

可感知

用户必须能够感知所有内容和 UI 组件。

色彩对比度

场景	最低对比度	增强级（AAA）
正文（< 18pt / < 14pt 粗体）	4.5 : 1	7 : 1
大号文本（≥ 18pt / ≥ 14pt 粗体）	3 : 1	4.5 : 1
UI 组件和图形对象	3 : 1	—

**请检查实际渲染页面上的对比度，而不是规格说明中的数值（dembrandt 引擎，可选）。**设计阶段的色板在真实文本置于真实背景、渐变和叠加层上时并不可靠。get_findings / render_report 会检查实时 DOM，并显示实际未达标的文本/背景组合及测得的对比度，这能快速发现静态调色板检查遗漏的问题。参见 extract-design。

**禁用元素不受此要求约束。**WCAG 明确将非活动 UI 组件排除在对比度要求之外（WCAG 1.4.3 的例外）。禁用按钮可以使用低对比度文本——这是有意为之，也是正确的，因为它传达了不可用状态。

不要只用颜色传达信息（例如，仅用红色边框表示错误——还应添加图标或文本标签）。

**字重也是易读性的一部分，而对比度公式无法衡量它。**对比度公式只测量前景文字颜色与背景颜色，不考虑其他因素。相同色相下，它对细字和粗字的评分完全相同，但感知易读性取决于两者。因此，调色板中最浅但仍易读的颜色，不应与字体比例中最轻的字重用于同一段文本：在正文默认字重为常规或偏轻的地方，承载说明文字、标签和辅助文本的柔和或次要色彩令牌，字重至少应为 500。这是团队规范，并非 WCAG 要求。该标准没有涉及字重，正因如此，这类问题才会通过审查。深色表面上的同样原理见 [[color-mode-and-theme]]。柔和色彩本来就是调色板中最不醒目的选择，再搭配最轻的字重，相当于叠加了两个都意在弱化视觉存在感的设计决定。在说明文字的字号下，读者必须刻意费力才能看清文本，而审查结果却显示通过。

文本替代内容

• 每张有意义的图片都需要使用 alt 文本描述其内容或功能
• 装饰性图片使用 alt=""，以便屏幕阅读器跳过
• 用作按钮的图标需要无障碍标签：aria-label 或视觉隐藏文本
• 图表和数据可视化需要提供文本摘要或数据表格作为替代内容

字幕和文字稿

• 视频内容需要字幕
• 纯音频内容需要文字稿

---

可操作

用户必须能够操作所有 UI 组件。

键盘导航

所有交互元素都必须能够仅通过键盘访问和操作。

• 每个按钮、链接、输入框和控件都必须能够通过 Tab 获得焦点
• 焦点顺序必须遵循页面的视觉阅读顺序
• 不得存在键盘陷阱——用户必须能够离开任何组件
• 模态对话框打开时必须将焦点限制在对话框内，关闭时将焦点返回触发元素

焦点可见性

每个交互元素都必须有可见的焦点指示器（WCAG 2.2 加强了对焦点可见性的要求）。

/* Minimum: do not remove focus outline without a replacement */
:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

除非提供自定义焦点样式，否则切勿使用 outline: none。焦点环不是需要消除的设计问题，而是一种导航工具。

触控目标尺寸

触控设备上的交互元素尺寸必须至少为 24×24px（WCAG 2.2）——推荐的舒适最小尺寸为 44×44px（Apple HIG、Material Design）。小型图标按钮需要添加内边距以达到此尺寸，即使图标本身更小。

避免触发癫痫

屏幕上的任何内容每秒闪烁都不应超过 3 次。

跳过链接

包含重复导航的页面必须将“跳至主要内容”链接设为第一个可聚焦元素，以便键盘用户在每个页面上都能跳过导航。

---

易于理解

用户必须能够理解内容以及 UI 的运作方式。

语言

• 在 <html> 元素上设置 lang 属性：<html lang="fi"> 或 <html lang="en">
• 对使用不同语言的内联内容，在相应元素上标记 lang

标签和说明

• 每个表单输入项都必须有可见标签，而不仅仅是占位符（输入内容后占位符会消失）
• 必填字段必须明确标示——不要只依赖颜色；请添加星号和说明
• 错误消息必须通过 aria-describedby 与对应输入项关联

可预测性

• 外观相同的组件必须具有相同行为（参见“一致性和标准”）
• 不同页面上的导航必须位于相同位置
• 必须提前告知用户会打开新标签页或窗口

错误识别

• 表单验证错误必须指出出错的字段
• 错误必须以文本描述，而不能只通过颜色或图标表示

---

稳健性

辅助技术必须能够可靠地解读内容。

语义化 HTML

针对不同用途使用正确的 HTML 元素。语义会自动向屏幕阅读器传达角色、状态和结构。

<button>Save</button>
<nav aria-label="Main navigation">...</nav>
<h1>Page title</h1>


<div onclick="save()">Save</div>
<div class="nav">...</div>
<div class="heading">Page title</div>

ARIA — 谨慎使用

当原生 HTML 元素无法满足需求时，ARIA 可补充 HTML 语义，但无法修复有问题的 HTML。

规则：不使用 ARIA 好过错误使用 ARIA。 错误的 ARIA 会直接破坏屏幕阅读器的输出。

必需模式：

• 对没有可见文本标签的组件，使用 aria-label 或 aria-labelledby
• 在切换开关、手风琴和下拉菜单上使用 aria-expanded
• 对动态内容更新（Toast 通知、搜索结果）使用 aria-live 区域
• 在模态覆盖层上使用 role="dialog" 和 aria-modal="true"
• 在当前活动的导航项上使用 aria-current="page"

状态消息

动态更新（成功提示、加载状态、错误计数）必须通过 aria-live 或 role="status" 通知屏幕阅读器——除非焦点元素发生变化，否则屏幕阅读器不会自动播报这些更新。

---

禁用元素例外

WCAG 1.4.3 明确规定：“属于非活动用户界面组件一部分的文本或文本图像……没有对比度要求。”

这意味着：

• 禁用按钮、输入项和链接可以使用低对比度文本和颜色
• 对禁用状态进行视觉淡化既正确又符合规范
• 不要人为提高禁用元素的对比度——降低对比度传达了“此项不可用”

---

审查清单

范围	检查项
对比度	所有活动文本的对比度均 ≥ 4.5:1（普通文本）或 3:1（大号文本／UI）
对比度	禁用元素不受此要求限制——有意采用低对比度是可以的
颜色	颜色绝不能是唯一的信息载体
键盘	所有交互元素均可通过键盘访问和操作
焦点	每个交互元素都有可见的焦点指示器
触控	触控界面上的交互目标尺寸均 ≥ 44×44px
标签	每个输入框都有可见标签（不能只有占位符）
错误	验证错误会指出出错字段，并以文本描述问题
HTML	正确使用语义元素；仅在需要时使用 ARIA
语言	在 <html> 上设置 lang 属性
跳转链接	将“跳转到主要内容”设为第一个可聚焦元素
实时区域	通过 aria-live 或 role="status" 播报动态更新