wcag-compliance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

WCAG Compliance

WCAG合规性

Web Content Accessibility Guidelines 2.2 AA implementation for inclusive, legally compliant web applications.
为具有包容性、符合法律要求的Web应用实现Web内容无障碍指南(WCAG)2.2 AA标准。

Overview

概述

  • Building accessible UI components from scratch
  • Auditing applications for ADA/Section 508 compliance
  • Implementing keyboard navigation and focus management
  • Supporting screen readers and assistive technologies
  • Fixing color contrast and visual accessibility issues
  • 从零开始构建无障碍UI组件
  • 审计应用是否符合ADA/Section 508合规要求
  • 实现键盘导航与焦点管理
  • 支持屏幕阅读器及辅助技术
  • 修复色彩对比度与视觉无障碍问题

Quick Reference

快速参考

Semantic HTML Structure

语义化HTML结构

tsx
<main>
  <article>
    <header><h1>Page Title</h1></header>
    <section aria-labelledby="features-heading">
      <h2 id="features-heading">Features</h2>
      <ul><li>Feature 1</li></ul>
    </section>
    <aside aria-label="Related content">...</aside>
  </article>
</main>
tsx
<main>
  <article>
    <header><h1>Page Title</h1></header>
    <section aria-labelledby="features-heading">
      <h2 id="features-heading">Features</h2>
      <ul><li>Feature 1</li></ul>
    </section>
    <aside aria-label="Related content">...</aside>
  </article>
</main>

ARIA Labels and States

ARIA标签与状态

tsx
// Icon-only button
<button aria-label="Save document">
  <svg aria-hidden="true">...</svg>
</button>

// Form field with error
<input
  id="email"
  aria-required="true"
  aria-invalid={!!error}
  aria-describedby={error ? "email-error" : "email-hint"}
/>
{error && <p id="email-error" role="alert">{error}</p>}
tsx
// Icon-only button
<button aria-label="Save document">
  <svg aria-hidden="true">...</svg>
</button>

// Form field with error
<input
  id="email"
  aria-required="true"
  aria-invalid={!!error}
  aria-describedby={error ? "email-error" : "email-hint"}
/>
{error && <p id="email-error" role="alert">{error}</p>}

Color Contrast (CSS)

色彩对比度(CSS)

css
:root {
  --text-primary: #1a1a1a;   /* 16.1:1 on white - normal text */
  --text-secondary: #595959; /* 7.0:1 on white - secondary */
  --focus-ring: #0052cc;     /* 7.3:1 - focus indicator */
}
:focus-visible {
  outline: 3px solid var(--focus-ring);
  outline-offset: 2px;
}
css
:root {
  --text-primary: #1a1a1a;   /* 16.1:1 on white - normal text */
  --text-secondary: #595959; /* 7.0:1 on white - secondary */
  --focus-ring: #0052cc;     /* 7.3:1 - focus indicator */
}
:focus-visible {
  outline: 3px solid var(--focus-ring);
  outline-offset: 2px;
}

WCAG 2.2 AA Checklist

WCAG 2.2 AA检查清单

CriterionRequirementTest
1.1.1 Non-textAlt text for imagesaxe-core scan
1.3.1 InfoSemantic HTML, headingsManual + automated
1.4.3 Contrast4.5:1 text, 3:1 largeWebAIM checker
1.4.11 Non-text Contrast3:1 UI componentsManual inspection
2.1.1 KeyboardAll functionality via keyboardTab through
2.4.3 Focus OrderLogical tab sequenceManual test
2.4.7 Focus VisibleClear focus indicatorVisual check
2.4.11 Focus Not ObscuredFocus not hidden by sticky elementsscroll-margin-top
2.5.7 DraggingSingle-pointer alternativeButton fallback
2.5.8 Target SizeMin 24x24px interactiveCSS audit
4.1.2 Name/Role/ValueProper ARIA, labelsScreen reader test
准则要求测试方式
1.1.1 非文本内容图片的替代文本axe-core扫描
1.3.1 信息与关系语义化HTML、标题人工+自动化
1.4.3 对比度普通文本4.5:1,大文本3:1WebAIM检查工具
1.4.11 非文本对比度UI组件3:1人工检查
2.1.1 键盘可达性所有功能均可通过键盘操作按Tab键遍历
2.4.3 焦点顺序符合逻辑的Tab序列人工测试
2.4.7 焦点可见清晰的焦点指示器视觉检查
2.4.11 焦点不被遮挡焦点不被固定元素遮挡scroll-margin-top属性设置
2.5.7 拖拽操作单指针操作替代方案按钮回退方案
2.5.8 目标尺寸交互元素最小24x24pxCSS审计
4.1.2 名称/角色/值正确使用ARIA、标签屏幕阅读器测试

Key Decisions

关键决策

DecisionChoiceRationale
Conformance levelWCAG 2.2 AALegal standard (ADA, Section 508)
Contrast ratio4.5:1 normal, 3:1 largeAA minimum requirement
Target size24px min, 44px touch2.5.8 + mobile usability
Focus indicator3px solid outlineHigh visibility, 3:1 contrast
Live regionspolite default, assertive for errorsAvoids interruption
Decorative imagesalt="" role="presentation"Hide from AT
Skip linkFirst focusable elementKeyboard user efficiency
决策项选择理由
合规等级WCAG 2.2 AA法律标准(ADA、Section 508)
对比度比值普通文本4.5:1,大文本3:1AA级最低要求
目标尺寸最小24px,触摸元素44px2.5.8标准+移动可用性
焦点指示器3px实线外框高可见性,3:1对比度
实时区域默认polite,错误提示用assertive避免干扰用户
装饰性图片alt="" role="presentation"对辅助技术隐藏
跳转链接第一个可聚焦元素提升键盘用户效率

Anti-Patterns (FORBIDDEN)

反模式(禁止使用)

  • Div soup: Using
    <div>
    instead of semantic elements (
    <nav>
    ,
    <main>
    ,
    <article>
    )
  • Color-only information: Status indicated only by color without icon/text
  • Missing labels: Form inputs without associated
    <label>
    or
    aria-label
  • Keyboard traps: Focus that cannot escape without mouse
  • Auto-playing media: Audio/video that plays without user action
  • Removing focus outline:
    outline: none
    without replacement indicator
  • Positive tabindex: Using
    tabindex > 0
    (disrupts natural order)
  • Empty links/buttons: Interactive elements without accessible names
  • ARIA overuse: Using ARIA when semantic HTML suffices
  • Div标签滥用:使用
    <div>
    而非语义化元素(
    <nav>
    <main>
    <article>
  • 仅用颜色传递信息:仅通过颜色而非图标/文本表示状态
  • 缺失标签:表单输入框未关联
    <label>
    aria-label
  • 键盘陷阱:焦点无法通过键盘离开,必须使用鼠标
  • 自动播放媒体:未经用户操作自动播放音频/视频
  • 移除焦点外框:使用
    outline: none
    且未提供替代指示器
  • 正tabindex值:使用
    tabindex > 0
    (破坏自然顺序)
  • 空链接/按钮:交互元素无无障碍名称
  • 过度使用ARIA:语义化HTML可满足需求时仍使用ARIA

Related Skills

相关技能

  • a11y-testing
    - Automated accessibility testing with axe-core and Playwright
  • design-system-starter
    - Accessible component library patterns
  • i18n-date-patterns
    - RTL layout and locale-aware formatting
  • motion-animation-patterns
    - Reduced motion and animation accessibility
  • a11y-testing
    - 基于axe-core和Playwright的自动化无障碍测试
  • design-system-starter
    - 无障碍组件库模式
  • i18n-date-patterns
    - RTL布局与区域化格式
  • motion-animation-patterns
    - 减少动画与无障碍适配

Capability Details

能力细节

semantic-html

semantic-html

Keywords: semantic, landmark, heading, structure, html5, main, nav, article Solves:
  • Proper document structure with landmarks
  • Heading hierarchy (h1-h6 in order)
  • Form fieldsets and legends
  • Lists for grouped content
关键词: semantic, landmark, heading, structure, html5, main, nav, article 解决问题:
  • 使用地标元素构建规范的文档结构
  • 标题层级(h1-h6按顺序使用)
  • 表单字段集与图例
  • 分组内容使用列表

aria-patterns

aria-patterns

Keywords: aria, role, state, property, live-region, alert, status Solves:
  • Custom widget accessibility (tabs, menus, dialogs)
  • Dynamic content announcements
  • Expanded/collapsed states
  • Error/validation messaging
关键词: aria, role, state, property, live-region, alert, status 解决问题:
  • 自定义组件无障碍适配(标签页、菜单、对话框)
  • 动态内容的辅助技术播报
  • 展开/折叠状态标识
  • 错误/验证消息提示

focus-management

focus-management

Keywords: keyboard, focus, tab, trap, modal, skip-link, roving Solves:
  • Modal focus trapping
  • Skip links for navigation
  • Roving tabindex for widgets
  • Focus restoration after dialogs
关键词: keyboard, focus, tab, trap, modal, skip-link, roving 解决问题:
  • 模态框焦点捕获
  • 导航跳转链接
  • 组件的roving tabindex实现
  • 对话框关闭后恢复焦点

color-contrast

color-contrast

Keywords: contrast, color, wcag, perceivable, vision, ratio Solves:
  • Text contrast ratios (4.5:1 / 3:1)
  • UI component contrast (3:1)
  • Focus indicator visibility
  • Non-color status indicators
关键词: contrast, color, wcag, perceivable, vision, ratio 解决问题:
  • 文本对比度比值(4.5:1 / 3:1)
  • UI组件对比度(3:1)
  • 焦点指示器可见性
  • 非颜色状态标识