accessibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web Accessibility

Web无障碍

Accessibility is not a feature you bolt on at the end -- it is a quality attribute that must be considered from the first line of markup. Building accessible interfaces means that people with visual, motor, auditory, or cognitive disabilities can perceive, navigate, and interact with your application. It also means better usability for everyone: keyboard power users, people on slow connections, users with temporary injuries, and those in constrained environments.

无障碍不是你在项目最后才附加的功能——它是从第一行标记代码开始就必须考虑的质量属性。构建无障碍界面意味着有视觉、运动、听觉或认知障碍的用户也能够感知、导航并使用你的应用，同时还能为所有用户带来更好的可用性：键盘高阶用户、弱网环境用户、临时受伤的用户以及处于受限环境的用户都能从中受益。

Why Accessibility Matters

无障碍的重要性

Dimension	Impact
Legal	Legislation in most jurisdictions (ADA, EAA, Section 508, EN 301 549) requires digital products to be accessible. Non-compliance carries litigation risk and financial penalties.
Ethical	Roughly 16% of the global population lives with some form of disability. Excluding them from digital services is a choice, not an inevitability.
Business	Accessible products reach a wider audience, improve SEO (structured content helps crawlers), reduce support costs, and correlate with higher overall usability scores.
Technical quality	Accessibility constraints force clean markup, proper semantics, and separation of concerns -- all of which improve maintainability.

维度	影响
法律层面	大多数司法管辖区的立法（ADA、EAA、第508条款、EN 301 549）都要求数字产品具备可访问性，不合规会带来诉讼风险和经济处罚。
伦理层面	全球约有16%的人口存在某种形式的残疾，将他们排除在数字服务之外是人为选择，而非不可避免的结果。
商业层面	无障碍产品能够覆盖更广泛的受众，提升SEO效果（结构化内容对爬虫更友好），降低支持成本，同时往往对应更高的整体可用性评分。
技术质量层面	无障碍约束会倒逼开发者编写干净的标记代码、使用合理的语义、实现关注点分离，这些都能提升代码的可维护性。

WCAG Principles: POUR

WCAG原则：POUR

The Web Content Accessibility Guidelines organize all success criteria under four principles. Every accessibility requirement maps to at least one.

Principle	Question It Answers	Examples
Perceivable	Can users sense the content?	Text alternatives for images, captions for video, sufficient color contrast, resizable text
Operable	Can users interact with every control?	Keyboard operability, enough time to complete tasks, no seizure-triggering animations, clear navigation
Understandable	Can users comprehend the content and UI behavior?	Readable language, predictable navigation, input assistance and error messages
Robust	Does it work across assistive technologies?	Valid markup, proper use of ARIA, compatibility with screen readers and other tools

《Web内容无障碍指南》将所有成功标准归为四大原则，每一项无障碍要求至少对应其中一项原则。

原则	回答的问题	示例
可感知（Perceivable）	用户能否感知到内容？	图片的文本替代说明、视频字幕、足够的色彩对比度、可调整大小的文本
可操作（Operable）	用户能否与所有控件交互？	键盘可操作、充足的任务完成时间、无诱发癫痫的动画、清晰的导航
可理解（Understandable）	用户能否理解内容和UI的行为逻辑？	易懂的语言、可预测的导航、输入辅助和错误提示
健壮性（Robust）	能否在各类辅助技术上正常运行？	合法的标记代码、正确使用ARIA、兼容屏幕阅读器和其他工具

Conformance Levels

合规等级

WCAG defines three levels. Each higher level includes all criteria from the levels below it.

Level	Target Audience	Typical Requirement
A	Bare minimum -- removes the most severe barriers	Most legal and procurement requirements start here
AA	Industry standard -- addresses the majority of barriers for most users	Required by ADA, EAA, Section 508, and most organizational policies
AAA	Highest standard -- not always achievable for all content types	Aspirational goal; apply selectively where feasible

For most projects, target Level AA. It covers the vast majority of real-world accessibility needs without imposing requirements that conflict with certain content types.

WCAG定义了三个等级，更高等级包含所有低等级的要求。

等级	适用受众	典型要求
A	最低要求——消除最严重的访问障碍	大多数法律和采购要求的最低门槛
AA	行业标准——解决大多数用户面临的绝大多数障碍	ADA、EAA、第508条款和大多数组织政策的强制要求
AAA	最高标准——并非所有内容类型都能实现	愿景目标，在可行的场景下选择性应用

对于大多数项目，以AA级为目标即可，它覆盖了绝大多数实际场景的无障碍需求，不会出现与特定内容类型冲突的要求。

Semantic HTML Fundamentals

语义化HTML基础

Native HTML elements carry built-in semantics, keyboard behavior, and screen reader announcements. Using the right element is the single most effective accessibility technique.

Instead Of	Use	Why
`<div onclick="...">`	`<button>`	Buttons are focusable, announce their role, and respond to Enter and Space
`<span class="link">`	`<a href="...">`	Links announce as "link," support middle-click, and appear in link lists
`<div class="header">`	`<header>` , `<nav>` , `<main>` , `<footer>`	Landmark elements let screen reader users jump between page regions
`<div class="list">`	`<ul>` / `<ol>` with `<li>`	Lists announce item count and position ("item 3 of 7")
`<div class="table">`	`<table>` with `<th>`	Table headers associate data cells with their labels for screen readers
Styled `<div>` for input	`<input>` , `<select>` , `<textarea>`	Native form controls have label association, validation, and assistive tech support built in

原生HTML元素自带内置语义、键盘行为和屏幕阅读器播报逻辑，使用正确的元素是性价比最高的无障碍优化手段。

不推荐写法	推荐写法	原因
`<div onclick="...">`	`<button>`	按钮默认可聚焦、会播报自身角色、支持Enter和Space键触发
`<span class="link">`	`<a href="...">`	链接会被播报为「链接」、支持中键打开、会出现在链接列表中
`<div class="header">`	`<header>` 、 `<nav>` 、 `<main>` 、 `<footer>`	地标元素让屏幕阅读器用户可以在页面区域之间快速跳转
`<div class="list">`	搭配 `<li>` 的 `<ul>` / `<ol>`	列表会播报条目总数和位置（「共7条，第3条」）
`<div class="table">`	搭配 `<th>` 的 `<table>`	表头会将数据单元格和对应标签关联，方便屏幕阅读器识别
用样式化 `<div>` 做输入框	`<input>` 、 `<select>` 、 `<textarea>`	原生表单控件自带标签关联、校验和辅助技术支持

Heading Hierarchy

标题层级

Headings create an outline that screen reader users navigate like a table of contents. Follow these rules:

One
```
<h1>
```
per page that describes the page purpose
Never skip levels (do not jump from
```
<h2>
```
to
```
<h4>
```
)
Use headings for structure, not for visual styling -- CSS handles appearance

标题会生成页面大纲，屏幕阅读器用户可以像浏览目录一样导航。请遵循以下规则：

每个页面只有一个
```
<h1>
```
，用于描述页面用途
不要跳过层级（不要直接从
```
<h2>
```
跳到
```
<h4>
```
）
用标题做结构划分，不要为了视觉样式乱用标题——外观用CSS控制

Common Accessibility Issues

常见无障碍问题

Issue	Impact	Fix
Missing alt text on images	Screen readers announce the filename or nothing	Add descriptive `alt` ; use `alt=""` for purely decorative images
Insufficient color contrast	Users with low vision cannot read text	Meet 4.5:1 ratio for normal text, 3:1 for large text (AA)
No keyboard access to interactive elements	Keyboard and switch users are completely blocked	Use native interactive elements or add `tabindex="0"` and key handlers
Missing form labels	Screen readers cannot announce what an input is for	Associate every input with a `<label>` using `for` / `id` or wrapping
Auto-playing media	Disorienting for screen reader users, harmful for those with cognitive disabilities	Never auto-play; if unavoidable, provide a visible pause/stop control
Missing skip link	Keyboard users must tab through the entire nav on every page	Add a skip-to-main-content link as the first focusable element
No focus indicator	Keyboard users lose track of their position on the page	Never remove `outline` without providing a visible custom alternative
Missing page language	Screen readers may mispronounce content	Set `lang` attribute on `<html>` (e.g., `lang="en"` )
Inaccessible dynamic content	Screen readers do not announce changes that happen after page load	Use ARIA live regions to announce dynamic updates
Missing document title	Screen reader users cannot identify the page when switching tabs	Set a unique, descriptive `<title>` for every page
Touch targets too small	Motor-impaired users cannot reliably tap small controls	Minimum 24x24 CSS pixels (AA), prefer 44x44 for comfortable interaction
Motion and animation	Can cause vestigo, nausea, or seizures	Respect `prefers-reduced-motion` media query; never flash more than 3 times per second

问题	影响	修复方案
图片缺失alt文本	屏幕阅读器会播报文件名或者不播报任何内容	添加描述性的 `alt` 属性；纯装饰性图片使用 `alt=""`
色彩对比度不足	低视力用户无法看清文本	普通文本对比度达到4.5:1，大文本达到3:1（AA级要求）
交互元素不支持键盘访问	键盘和切换设备用户完全无法使用	使用原生交互元素，或者添加 `tabindex="0"` 和键盘事件处理逻辑
表单缺失标签	屏幕阅读器无法播报输入框的用途	通过 `for` / `id` 关联或者嵌套的方式，将每个输入框和 `<label>` 绑定
媒体自动播放	会让屏幕阅读器用户感到混乱，对认知障碍用户有害	永远不要自动播放；如果不可避免，要提供可见的暂停/停止控件
缺失跳转链接	键盘用户每次进入页面都需要tab遍历整个导航栏	添加跳转到主内容的链接作为页面第一个可聚焦元素
无焦点指示器	键盘用户无法追踪自己在页面中的位置	永远不要直接移除 `outline` ，要提供可见的自定义替代样式
缺失页面语言设置	屏幕阅读器可能会错误发音内容	在 `<html>` 标签上设置 `lang` 属性（比如 `lang="en"` ）
动态内容无无障碍适配	屏幕阅读器不会播报页面加载后发生的内容变化	使用ARIA live区域播报动态更新
缺失文档标题	屏幕阅读器用户切换标签时无法识别页面	为每个页面设置唯一、描述性的 `<title>`
触摸目标太小	运动障碍用户无法可靠点击小控件	最小24x24 CSS像素（AA级要求），优先使用44x44保证交互舒适度
动效和动画	可能导致眩晕、恶心或癫痫	尊重 `prefers-reduced-motion` 媒体查询；每秒闪烁次数永远不要超过3次

Accessible Forms

无障碍表单

Forms are where accessibility failures cause the most real-world harm -- users cannot complete purchases, registrations, or critical workflows.

表单是无障碍问题造成实际影响最严重的场景——用户会因此无法完成购买、注册或关键工作流程。

Label Association

标签关联

Every form control needs a programmatically associated label:

html

<!-- Explicit association -->
<label for="email">Email address</label>
<input type="email" id="email" name="email" required>

<!-- Implicit association (wrapping) -->
<label>
  Email address
  <input type="email" name="email" required>
</label>

每个表单控件都需要有程序层面关联的标签：

html

<!-- 显式关联 -->
<label for="email">Email address</label>
<input type="email" id="email" name="email" required>

<!-- 隐式关联（嵌套） -->
<label>
  Email address
  <input type="email" name="email" required>
</label>

Error Handling

错误处理

Display errors inline next to the relevant field, not only at the top of the form
Use
```
aria-describedby
```
to associate error messages with their input
Use
```
aria-invalid="true"
```
on fields that fail validation
Provide clear, specific error text ("Enter an email in the format name@example.com" not "Invalid input")

错误提示内联展示在对应字段旁，不要只放在表单顶部
使用
```
aria-describedby
```
将错误信息和对应输入框关联
校验失败的字段设置
```
aria-invalid="true"
```
提供清晰、具体的错误文本（比如「请输入格式为name@example.com的邮箱」，而不是「输入无效」）

Required Fields

必填字段

Mark required fields with
```
required
```
attribute (for native validation) or
```
aria-required="true"
```
(for custom validation)
Do not rely solely on color or an asterisk to indicate required status -- add text like "(required)"

用
```
required
```
属性（用于原生校验）或
```
aria-required="true"
```
（用于自定义校验）标记必填字段
不要只靠颜色或星号标识必填状态——添加「(必填)」之类的文本说明

Color and Contrast

色彩和对比度

Color must never be the only means of conveying information. Pair it with text, icons, patterns, or other visual cues.

Contrast ratios (WCAG AA):

Element	Minimum Ratio
Normal text (under 18pt / 14pt bold)	4.5:1
Large text (18pt+ / 14pt+ bold)	3:1
UI components and graphical objects	3:1

Quick wins:

Test with browser developer tools (Chrome DevTools shows contrast ratios on hover)
Respect
```
prefers-color-scheme
```
for dark mode support
Test designs with simulated color blindness (protanopia, deuteranopia, tritanopia)

永远不要把颜色作为传递信息的唯一手段，要搭配文本、图标、图案或其他视觉提示。

对比度要求（WCAG AA级）：

元素	最低对比度
普通文本（小于18pt / 14pt加粗）	4.5:1
大文本（18pt及以上 / 14pt加粗及以上）	3:1
UI组件和图形对象	3:1

快速优化技巧：

用浏览器开发者工具测试（Chrome DevTools hover时会显示对比度）
支持
```
prefers-color-scheme
```
适配深色模式
用模拟色盲模式测试设计（红色盲、绿色盲、蓝色盲）

Reference Files

参考文件

Reference	Contents
ARIA Patterns	When to use ARIA, roles and properties, widget patterns (tabs, modals, accordions, dropdowns), live regions, landmark roles
Keyboard and Focus	Tab order, arrow key navigation, focus trapping, skip links, focus restoration, visible focus indicators, touch targets
Testing Strategies	Automated tools, manual testing checklist, screen reader testing, contrast verification, accessibility tree, CI integration

参考	内容
ARIA模式	ARIA的使用场景、角色和属性、组件模式（标签页、模态框、手风琴、下拉菜单）、live区域、地标角色
键盘与焦点	Tab顺序、方向键导航、焦点 trapping、跳转链接、焦点恢复、可见焦点指示器、触摸目标
测试策略	自动化工具、手动测试 Checklist、屏幕阅读器测试、对比度校验、无障碍树、CI集成

Integration with Other Skills

与其他技能的集成

Situation	Recommended Skill
Building REST or GraphQL APIs with accessible error responses	Install `knowledge-virtuoso` from `krzysztofsurdy/code-virtuoso` for API design guidance
Security headers that affect accessibility (CSP, iframe restrictions)	Install `knowledge-virtuoso` from `krzysztofsurdy/code-virtuoso` for security patterns
Testing accessible components with unit and integration tests	Install `knowledge-virtuoso` from `krzysztofsurdy/code-virtuoso` for testing strategies
Performance optimization that does not sacrifice accessibility	Install `knowledge-virtuoso` from `krzysztofsurdy/code-virtuoso` for performance guidance

| 场景 | 推荐技能 | |---|---|---| | 构建具备无障碍错误响应的REST或GraphQL API | 从

krzysztofsurdy/code-virtuoso

安装

knowledge-virtuoso

获取API设计指导 | | 影响无障碍的安全头（CSP、iframe限制） | 从

krzysztofsurdy/code-virtuoso

安装

knowledge-virtuoso

获取安全模式指导 | | 对无障碍组件做单元和集成测试 | 从

krzysztofsurdy/code-virtuoso

安装

knowledge-virtuoso

获取测试策略指导 | | 不牺牲无障碍体验的性能优化 | 从

krzysztofsurdy/code-virtuoso

安装

knowledge-virtuoso

获取性能优化指导 |