Back to Details

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

无障碍的重要性

DimensionImpact
LegalLegislation in most jurisdictions (ADA, EAA, Section 508, EN 301 549) requires digital products to be accessible. Non-compliance carries litigation risk and financial penalties.
EthicalRoughly 16% of the global population lives with some form of disability. Excluding them from digital services is a choice, not an inevitability.
BusinessAccessible products reach a wider audience, improve SEO (structured content helps crawlers), reduce support costs, and correlate with higher overall usability scores.
Technical qualityAccessibility 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.
PrincipleQuestion It AnswersExamples
PerceivableCan users sense the content?Text alternatives for images, captions for video, sufficient color contrast, resizable text
OperableCan users interact with every control?Keyboard operability, enough time to complete tasks, no seizure-triggering animations, clear navigation
UnderstandableCan users comprehend the content and UI behavior?Readable language, predictable navigation, input assistance and error messages
RobustDoes 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.
LevelTarget AudienceTypical Requirement
ABare minimum -- removes the most severe barriersMost legal and procurement requirements start here
AAIndustry standard -- addresses the majority of barriers for most usersRequired by ADA, EAA, Section 508, and most organizational policies
AAAHighest standard -- not always achievable for all content typesAspirational 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 OfUseWhy
<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

常见无障碍问题

IssueImpactFix
Missing alt text on imagesScreen readers announce the filename or nothingAdd descriptive 
alt
; use 
alt=""
for purely decorative images
Insufficient color contrastUsers with low vision cannot read textMeet 4.5:1 ratio for normal text, 3:1 for large text (AA)
No keyboard access to interactive elementsKeyboard and switch users are completely blockedUse native interactive elements or add 
tabindex="0"
and key handlers
Missing form labelsScreen readers cannot announce what an input is forAssociate every input with a 
<label>
using 
for
/
id
or wrapping
Auto-playing mediaDisorienting for screen reader users, harmful for those with cognitive disabilitiesNever auto-play; if unavoidable, provide a visible pause/stop control
Missing skip linkKeyboard users must tab through the entire nav on every pageAdd a skip-to-main-content link as the first focusable element
No focus indicatorKeyboard users lose track of their position on the pageNever remove 
outline
without providing a visible custom alternative
Missing page languageScreen readers may mispronounce contentSet 
lang
attribute on 
<html>
(e.g., 
lang="en"
)
Inaccessible dynamic contentScreen readers do not announce changes that happen after page loadUse ARIA live regions to announce dynamic updates
Missing document titleScreen reader users cannot identify the page when switching tabsSet a unique, descriptive 
<title>
for every page
Touch targets too smallMotor-impaired users cannot reliably tap small controlsMinimum 24x24 CSS pixels (AA), prefer 44x44 for comfortable interaction
Motion and animationCan cause vestigo, nausea, or seizuresRespect 
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):
ElementMinimum Ratio
Normal text (under 18pt / 14pt bold)4.5:1
Large text (18pt+ / 14pt+ bold)3:1
UI components and graphical objects3: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

参考文件

ReferenceContents
ARIA PatternsWhen to use ARIA, roles and properties, widget patterns (tabs, modals, accordions, dropdowns), live regions, landmark roles
Keyboard and FocusTab order, arrow key navigation, focus trapping, skip links, focus restoration, visible focus indicators, touch targets
Testing StrategiesAutomated tools, manual testing checklist, screen reader testing, contrast verification, accessibility tree, CI integration
参考内容
ARIA模式ARIA的使用场景、角色和属性、组件模式（标签页、模态框、手风琴、下拉菜单）、live区域、地标角色
键盘与焦点Tab顺序、方向键导航、焦点 trapping、跳转链接、焦点恢复、可见焦点指示器、触摸目标
测试策略自动化工具、手动测试 Checklist、屏幕阅读器测试、对比度校验、无障碍树、CI集成

Integration with Other Skills

与其他技能的集成

SituationRecommended Skill
Building REST or GraphQL APIs with accessible error responsesInstall 
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 testsInstall 
knowledge-virtuoso
from 
krzysztofsurdy/code-virtuoso
for testing strategies
Performance optimization that does not sacrifice accessibilityInstall 
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
获取性能优化指导 |