无障碍工程师指南：WCAG 2.1 AA 合规、语义化HTML与键盘导航实践

Accessibility Engineer by daffy0208/ai-dev-standards

21 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/daffy0208/ai-dev-standards --skill 'Accessibility Engineer'

开发代码规范用户体验

🇨🇳中文介绍

无障碍工程师

为所有人构建——无障碍不是可选项。

核心理念

无障碍是一项公民权利，而非功能特性。

在美国，每四位成年人中就有一位患有残疾。无障碍设计惠及所有人：

视障用户（屏幕阅读器）
低视力用户（缩放、高对比度）
听障用户（字幕）
运动障碍用户（仅键盘操作）
认知障碍用户（清晰的语言）
暂时性障碍（手臂骨折）
情境限制（强光、嘈杂环境）

WCAG 合规级别

A 级： 最低要求（法律要求） AA 级： 行业标准（以此为目标） AAA 级： 黄金标准（对所有内容都难以实现）

目标：符合 WCAG 2.1 AA 标准

支柱一：语义化 HTML

使用正确的元素

// ❌ 不佳：所有内容都用 div（无语义含义）
<div onClick={handleClick}>Click me</div>
<div>Menu</div>

// ✅ 良好：语义化 HTML
<button onClick={handleClick}>Click me</button>
<nav>Menu</nav>

文档结构

// ✅ 正确的标题层级
<h1>Page Title</h1>
  <h2>Section 1</h2>
    <h3>Subsection 1.1</h3>
  <h2>Section 2</h2>

// ❌ 不佳：跳过层级
<h1>Page Title</h1>
  <h4>Section 1</h4> // 跳过了 h2, h3

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

支柱二：键盘导航

所有交互元素必须支持键盘访问

// ✅ 按钮默认支持键盘访问
<button onClick={handleClick}>Click me</button>

// ❌ Div 需要额外工作
<div onClick={handleClick}>Click me</div> // 无法通过 Tab 键聚焦！

// ✅ 如果必须使用 div，请添加键盘支持
<div
  role="button"
  tabIndex={0}
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      handleClick()
    }
  }}
>
  Click me
</div>

// ✅ 自然的 Tab 键顺序（遵循 DOM 顺序）
<input />
<button>Submit</button>
<a href="/help">Help</a>

// ❌ 不要使用 tabIndex > 0（破坏自然顺序）
<button tabIndex={5}>Button</button> // 反模式！

// ✅ tabIndex=-1 以从 Tab 键顺序中移除
<div tabIndex={-1}>Not keyboard focusable</div>

// 模态框：将焦点限制在内部
function Modal({ isOpen, onClose, children }) {
  const modalRef = useRef()

  useEffect(() => {
    if (!isOpen) return

    // 聚焦第一个可聚焦元素
    const firstFocusable = modalRef.current.querySelector('button, input, a')
    firstFocusable?.focus()

    // 限制焦点
    function handleTab(e) {
      if (e.key !== 'Tab') return

      const focusableElements = modalRef.current.querySelectorAll(
        'button, input, a, [tabindex]:not([tabindex="-1"])'
      )

      const first = focusableElements[0]
      const last = focusableElements[focusableElements.length - 1]

      if (e.shiftKey) {
        if (document.activeElement === first) {
          last.focus()
          e.preventDefault()
        }
      } else {
        if (document.activeElement === last) {
          first.focus()
          e.preventDefault()
        }
      }
    }

    document.addEventListener('keydown', handleTab)
    return () => document.removeEventListener('keydown', handleTab)
  }, [isOpen])

  return isOpen ? (
    <div role="dialog" aria-modal="true" ref={modalRef}>
      {children}
      <button onClick={onClose}>Close</button>
    </div>
  ) : null
}

// 允许键盘用户跳过导航
<a href="#main-content" className="skip-link">
  Skip to main content
</a>

<nav>{/* Navigation */}</nav>

<main id="main-content">
  {/* Main content */}
</main>

// CSS
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: #fff;
  padding: 8px;
}

.skip-link:focus {
  top: 0;
}

支柱三：ARIA 属性

仅在语义化 HTML 不足时使用 ARIA

// ✅ 语义化 HTML（无需 ARIA）
<button>Click me</button>

// ❌ 不必要的 ARIA
<button role="button" aria-label="Click me">Click me</button>

// ✅ 需要 ARIA（自定义组件）
<div role="tab" aria-selected={isActive} aria-controls="panel-1">
  Tab 1
</div>

aria-label - 提供无障碍名称：

<button aria-label="Close dialog">
  <XIcon /> {/* 仅视觉可见 */}
</button>

<input type="search" aria-label="Search products" />

aria-labelledby - 引用另一个元素：

<h2 id="dialog-title">Delete Account</h2>
<div role="dialog" aria-labelledby="dialog-title">
  {/* Dialog content */}
</div>

aria-describedby - 附加描述：

<input
  type="password"
  aria-describedby="password-requirements"
/>
<div id="password-requirements">
  Must be at least 8 characters
</div>

aria-live - 宣布动态内容：

// Polite：等待用户完成操作
<div aria-live="polite">
  {itemsAddedToCart} items added to cart
</div>

// Assertive：立即中断（谨慎使用）
<div aria-live="assertive" role="alert">
  Error: Payment failed
</div>

aria-expanded - 可折叠内容：

<button
  aria-expanded={isOpen}
  aria-controls="dropdown-menu"
  onClick={() => setIsOpen(!isOpen)}
>
  Menu
</button>

<div id="dropdown-menu" hidden={!isOpen}>
  {/* Menu items */}
</div>

aria-hidden - 对屏幕阅读器隐藏：

// 装饰性图标
<span aria-hidden="true">★</span>

// 不要隐藏交互元素！
// ❌ 不佳
<button aria-hidden="true">Click me</button>

支柱四：表单与输入

// ✅ 良好：显式标签
<label htmlFor="email">Email</label>
<input id="email" type="email" />

// ✅ 良好：隐式标签
<label>
  Email
  <input type="email" />
</label>

// ❌ 不佳：无标签（占位符不是标签！）
<input type="email" placeholder="Email" />

function EmailInput({ error }) {
  const errorId = 'email-error'

  return (
    <>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        aria-invalid={!!error}
        aria-describedby={error ? errorId : undefined}
      />
      {error && (
        <div id={errorId} role="alert">
          {error}
        </div>
      )}
    </>
  )
}

<label htmlFor="name">
  Name <span aria-label="required">*</span>
</label>
<input id="name" type="text" required aria-required="true" />

支柱五：颜色与对比度

最小对比度比率（WCAG AA）

普通文本（< 18pt）：4.5:1
大文本（≥ 18pt 或 14pt 粗体）：3:1
UI 组件：3:1

// ❌ 不佳：对比度不足
<button style={{ background: '#ddd', color: '#aaa' }}>
  Submit // 1.5:1 对比度 - 失败！
</button>

// ✅ 良好：对比度足够
<button style={{ background: '#0066cc', color: '#ffffff' }}>
  Submit // 8:1 对比度 - 通过！
</button>

不要仅使用颜色

// ❌ 不佳：仅使用颜色
<span style={{ color: 'red' }}>Error</span>
<span style={{ color: 'green' }}>Success</span>

// ✅ 良好：颜色 + 图标/文本
<span style={{ color: 'red' }}>
  <ErrorIcon aria-hidden="true" />
  Error
</span>

支柱六：图像与媒体

// ✅ 信息性图像
<img src="chart.png" alt="Sales increased 50% in Q4" />

// ✅ 装饰性图像
<img src="decorative-border.png" alt="" /> // 空 alt

// ❌ 不佳：无 alt 或冗余 alt
<img src="photo.jpg" /> // 缺少 alt
<img src="photo.jpg" alt="Photo" /> // 无意义

<figure>
  <img src="complex-chart.png" alt="Sales data for 2024" />
  <figcaption>
    <details>
      <summary>Detailed description</summary>
      <p>Q1: $100k, Q2: $150k, Q3: $180k, Q4: $220k. Shows 50% growth year-over-year.</p>
    </details>
  </figcaption>
</figure>

<video controls>
  <source src="video.mp4" type="video/mp4" />
  <track kind="captions" src="captions.vtt" srclang="en" label="English" default />
</video>

# Lighthouse 无障碍审计
lighthouse https://example.com --only-categories=accessibility

# axe-core (Jest)
npm install --save-dev @axe-core/react jest-axe

// 使用 jest-axe 测试
import { axe, toHaveNoViolations } from 'jest-axe'

expect.extend(toHaveNoViolations)

it('has no accessibility violations', async () => {
  const { container } = render(<Button>Click me</Button>)
  const results = await axe(container)

  expect(results).toHaveNoViolations()
})

用 Tab 键浏览整个页面
用 Enter/Space 键激活按钮
用方向键操作单选按钮组
用 Esc 键关闭模态框

屏幕阅读器测试：

NVDA（Windows，免费）
JAWS（Windows，付费）
VoiceOver（Mac，内置）

屏幕阅读器快捷键：

按标题导航：H（下一个），Shift+H（上一个）
按地标区域导航：D（下一个），Shift+D（上一个）
列出所有链接：Insert+F7（NVDA）

<button
  type="button"
  onClick={handleClick}
  disabled={isDisabled}
  aria-busy={isLoading}
  aria-label={ariaLabel}
>
  {children}
</button>

<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
  aria-describedby="dialog-description"
>
  <h2 id="dialog-title">Dialog Title</h2>
  <p id="dialog-description">Dialog description</p>

  <button onClick={onClose}>Close</button>
</div>

<div>
  <div role="tablist">
    <button
      role="tab"
      aria-selected={activeTab === 'tab1'}
      aria-controls="panel1"
      onClick={() => setActiveTab('tab1')}
    >
      Tab 1
    </button>
    <button
      role="tab"
      aria-selected={activeTab === 'tab2'}
      aria-controls="panel2"
      onClick={() => setActiveTab('tab2')}
    >
      Tab 2
    </button>
  </div>

  <div id="panel1" role="tabpanel" hidden={activeTab !== 'tab1'}>
    Panel 1 content
  </div>

  <div id="panel2" role="tabpanel" hidden={activeTab !== 'tab2'}>
    Panel 2 content
  </div>
</div>

无障碍检查清单

正确的标题层级（h1 → h2 → h3）
语义化地标区域（header, nav, main, footer）
列表使用 ul/ol/li
按钮用于操作，链接用于导航

所有交互元素都支持键盘访问
可见的焦点指示器
逻辑化的 Tab 键顺序
提供跳过链接
无键盘陷阱

优先使用语义化 HTML（仅在需要时使用 ARIA）
所有交互式组件都有角色定义
动态内容有 aria-live 属性
表单有正确的标签和描述

文本对比度 ≥ 4.5:1（普通），≥ 3:1（大文本）
不要仅用颜色传达信息
焦点指示器可见

所有图像都有替代文本
装饰性图像有空的 alt 属性
视频有字幕
音频有文字稿

所有输入都有标签
错误信息与输入关联
必填字段有标识

测试键盘导航
测试屏幕阅读器
运行自动化工具（axe, Lighthouse）
测试色盲模拟

axe DevTools - 浏览器扩展
Lighthouse - Chrome DevTools 内置
WAVE - 网页无障碍评估工具
Color Contrast Analyzer - 桌面应用
NVDA - 免费屏幕阅读器（Windows）
VoiceOver - 内置屏幕阅读器（Mac）

ux-designer - 无障碍设计模式
frontend-builder - 无障碍 React 组件
testing-strategist - 无障碍测试

为所有人构建。 ♿

🇺🇸English

Accessibility Engineer

Build for everyone - accessibility is not optional.

Core Principle

Accessibility is a civil right, not a feature.

1 in 4 adults in the US has a disability. Accessible design benefits everyone:

Blind users (screen readers)
Low vision users (zoom, high contrast)
Deaf users (captions)
Motor disabilities (keyboard-only)
Cognitive disabilities (clear language)
Temporary disabilities (broken arm)
Situational limitations (bright sunlight, noisy environment)

WCAG Compliance Levels

Level A: Minimum (legal requirement) Level AA: Industry standard (aim for this) Level AAA: Gold standard (difficult to achieve for all content)

Target: WCAG 2.1 AA compliance

Pillar 1: Semantic HTML

Use the Right Elements

// ❌ Bad: Divs for everything (no semantic meaning)
<div onClick={handleClick}>Click me</div>
<div>Menu</div>

// ✅ Good: Semantic HTML
<button onClick={handleClick}>Click me</button>
<nav>Menu</nav>

Document Structure

// ✅ Proper heading hierarchy
<h1>Page Title</h1>
  <h2>Section 1</h2>
    <h3>Subsection 1.1</h3>
  <h2>Section 2</h2>

// ❌ Bad: Skipping levels
<h1>Page Title</h1>
  <h4>Section 1</h4> // Skipped h2, h3

Landmarks

<header>
  <nav aria-label="Main navigation">
    {/* Navigation links */}
  </nav>
</header>

<main>
  <article>
    {/* Main content */}
  </article>

  <aside>
    {/* Sidebar */}
  </aside>
</main>

<footer>
  {/* Footer content */}
</footer>

Pillar 2: Keyboard Navigation

All Interactive Elements Must Be Keyboard Accessible

// ✅ Button is keyboard accessible by default
<button onClick={handleClick}>Click me</button>

// ❌ Div requires extra work
<div onClick={handleClick}>Click me</div> // Can't tab to it!

// ✅ If you must use div, add keyboard support
<div
  role="button"
  tabIndex={0}
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      handleClick()
    }
  }}
>
  Click me
</div>

Tab Order

// ✅ Natural tab order (follows DOM order)
<input />
<button>Submit</button>
<a href="/help">Help</a>

// ❌ Don't use tabIndex > 0 (breaks natural order)
<button tabIndex={5}>Button</button> // Anti-pattern!

// ✅ tabIndex=-1 to remove from tab order
<div tabIndex={-1}>Not keyboard focusable</div>

Focus Management

// Modal: Trap focus inside
function Modal({ isOpen, onClose, children }) {
  const modalRef = useRef()

  useEffect(() => {
    if (!isOpen) return

    // Focus first focusable element
    const firstFocusable = modalRef.current.querySelector('button, input, a')
    firstFocusable?.focus()

    // Trap focus
    function handleTab(e) {
      if (e.key !== 'Tab') return

      const focusableElements = modalRef.current.querySelectorAll(
        'button, input, a, [tabindex]:not([tabindex="-1"])'
      )

      const first = focusableElements[0]
      const last = focusableElements[focusableElements.length - 1]

      if (e.shiftKey) {
        if (document.activeElement === first) {
          last.focus()
          e.preventDefault()
        }
      } else {
        if (document.activeElement === last) {
          first.focus()
          e.preventDefault()
        }
      }
    }

    document.addEventListener('keydown', handleTab)
    return () => document.removeEventListener('keydown', handleTab)
  }, [isOpen])

  return isOpen ? (
    <div role="dialog" aria-modal="true" ref={modalRef}>
      {children}
      <button onClick={onClose}>Close</button>
    </div>
  ) : null
}

Skip Links

// Allow keyboard users to skip navigation
<a href="#main-content" className="skip-link">
  Skip to main content
</a>

<nav>{/* Navigation */}</nav>

<main id="main-content">
  {/* Main content */}
</main>

// CSS
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: #fff;
  padding: 8px;
}

.skip-link:focus {
  top: 0;
}

Pillar 3: ARIA Attributes

Only Use ARIA When Semantic HTML Isn't Enough

// ✅ Semantic HTML (no ARIA needed)
<button>Click me</button>

// ❌ Unnecessary ARIA
<button role="button" aria-label="Click me">Click me</button>

// ✅ ARIA needed (custom widget)
<div role="tab" aria-selected={isActive} aria-controls="panel-1">
  Tab 1
</div>

Common ARIA Attributes

aria-label - Provides accessible name:

<button aria-label="Close dialog">
  <XIcon /> {/* Visual only */}
</button>

<input type="search" aria-label="Search products" />

aria-labelledby - References another element:

<h2 id="dialog-title">Delete Account</h2>
<div role="dialog" aria-labelledby="dialog-title">
  {/* Dialog content */}
</div>

aria-describedby - Additional description:

<input
  type="password"
  aria-describedby="password-requirements"
/>
<div id="password-requirements">
  Must be at least 8 characters
</div>

aria-live - Announce dynamic content:

// Polite: Wait for user to finish
<div aria-live="polite">
  {itemsAddedToCart} items added to cart
</div>

// Assertive: Interrupt immediately (use sparingly)
<div aria-live="assertive" role="alert">
  Error: Payment failed
</div>

aria-expanded - Collapsible content:

<button
  aria-expanded={isOpen}
  aria-controls="dropdown-menu"
  onClick={() => setIsOpen(!isOpen)}
>
  Menu
</button>

<div id="dropdown-menu" hidden={!isOpen}>
  {/* Menu items */}
</div>

aria-hidden - Hide from screen readers:

// Decorative icons
<span aria-hidden="true">★</span>

// Don't hide interactive elements!
// ❌ Bad
<button aria-hidden="true">Click me</button>

Pillar 4: Forms & Inputs

Labels

// ✅ Good: Explicit label
<label htmlFor="email">Email</label>
<input id="email" type="email" />

// ✅ Good: Implicit label
<label>
  Email
  <input type="email" />
</label>

// ❌ Bad: No label (placeholder is not a label!)
<input type="email" placeholder="Email" />

Error Messages

function EmailInput({ error }) {
  const errorId = 'email-error'

  return (
    <>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        aria-invalid={!!error}
        aria-describedby={error ? errorId : undefined}
      />
      {error && (
        <div id={errorId} role="alert">
          {error}
        </div>
      )}
    </>
  )
}

Required Fields

<label htmlFor="name">
  Name <span aria-label="required">*</span>
</label>
<input id="name" type="text" required aria-required="true" />

Pillar 5: Color & Contrast

Minimum Contrast Ratios (WCAG AA)

Normal text (< 18pt): 4.5:1
Large text (≥ 18pt or 14pt bold): 3:1
UI components: 3:1

// ❌ Bad: Insufficient contrast <button style={{ background: '#ddd', color: '#aaa' }}> Submit // 1.5:1 contrast - fails! </button>

// ✅ Good: Sufficient contrast <button style={{ background: '#0066cc', color: '#ffffff' }}> Submit // 8:1 contrast - passes! </button>

Don't Use Color Alone

// ❌ Bad: Color only
<span style={{ color: 'red' }}>Error</span>
<span style={{ color: 'green' }}>Success</span>

// ✅ Good: Color + icon/text
<span style={{ color: 'red' }}>
  <ErrorIcon aria-hidden="true" />
  Error
</span>

Pillar 6: Images & Media

Alt Text

// ✅ Informative images
<img src="chart.png" alt="Sales increased 50% in Q4" />

// ✅ Decorative images
<img src="decorative-border.png" alt="" /> // Empty alt

// ❌ Bad: No alt or redundant alt
<img src="photo.jpg" /> // Missing alt
<img src="photo.jpg" alt="Photo" /> // Useless

Complex Images

<figure>
  <img src="complex-chart.png" alt="Sales data for 2024" />
  <figcaption>
    <details>
      <summary>Detailed description</summary>
      <p>Q1: $100k, Q2: $150k, Q3: $180k, Q4: $220k. Shows 50% growth year-over-year.</p>
    </details>
  </figcaption>
</figure>

Video Captions

<video controls>
  <source src="video.mp4" type="video/mp4" />
  <track kind="captions" src="captions.vtt" srclang="en" label="English" default />
</video>

Pillar 7: Testing

Automated Testing

# Lighthouse accessibility audit
lighthouse https://example.com --only-categories=accessibility

# axe-core (Jest)
npm install --save-dev @axe-core/react jest-axe



// Test with jest-axe
import { axe, toHaveNoViolations } from 'jest-axe'

expect.extend(toHaveNoViolations)

it('has no accessibility violations', async () => {
  const { container } = render(<Button>Click me</Button>)
  const results = await axe(container)

  expect(results).toHaveNoViolations()
})

Manual Testing

Keyboard Navigation:

Tab through entire page
Enter/Space to activate buttons
Arrow keys for radio groups
Esc to close modals

Screen Reader Testing:

NVDA (Windows, free)
JAWS (Windows, paid)
VoiceOver (Mac, built-in)

Screen Reader Shortcuts:

Navigate by headings: H (next), Shift+H (previous)
Navigate by landmarks: D (next), Shift+D (previous)
List all links: Insert+F7 (NVDA)

Common Patterns

Accessible Button

<button
  type="button"
  onClick={handleClick}
  disabled={isDisabled}
  aria-busy={isLoading}
  aria-label={ariaLabel}
>
  {children}
</button>

Accessible Modal

<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
  aria-describedby="dialog-description"
>
  <h2 id="dialog-title">Dialog Title</h2>
  <p id="dialog-description">Dialog description</p>

  <button onClick={onClose}>Close</button>
</div>

Accessible Tabs

<div>
  <div role="tablist">
    <button
      role="tab"
      aria-selected={activeTab === 'tab1'}
      aria-controls="panel1"
      onClick={() => setActiveTab('tab1')}
    >
      Tab 1
    </button>
    <button
      role="tab"
      aria-selected={activeTab === 'tab2'}
      aria-controls="panel2"
      onClick={() => setActiveTab('tab2')}
    >
      Tab 2
    </button>
  </div>

  <div id="panel1" role="tabpanel" hidden={activeTab !== 'tab1'}>
    Panel 1 content
  </div>

  <div id="panel2" role="tabpanel" hidden={activeTab !== 'tab2'}>
    Panel 2 content
  </div>
</div>

Accessibility Checklist

Semantic HTML

Proper heading hierarchy (h1 → h2 → h3)
Semantic landmarks (header, nav, main, footer)
Lists use ul/ol/li
Buttons for actions, links for navigation

Keyboard

All interactive elements keyboard accessible
Visible focus indicators
Logical tab order
Skip links provided
No keyboard traps

ARIA

Semantic HTML used first (ARIA only when needed)
All interactive widgets have roles
Dynamic content has aria-live
Forms have proper labels and descriptions

Color & Contrast

Text contrast ≥ 4.5:1 (normal), ≥ 3:1 (large)
Don't use color alone to convey info
Focus indicators visible

Images & Media

All images have alt text
Decorative images have empty alt
Videos have captions
Audio has transcripts

Forms

All inputs have labels
Error messages associated with inputs
Required fields indicated

Testing

Keyboard navigation tested
Screen reader tested
Automated tools run (axe, Lighthouse)
Color blindness simulation tested

Tools

axe DevTools - Browser extension
Lighthouse - Built into Chrome DevTools
WAVE - Web accessibility evaluation tool
Color Contrast Analyzer - Desktop app
NVDA - Free screen reader (Windows)
VoiceOver - Built-in screen reader (Mac)

Related Resources

Skills:

ux-designer - Accessible design patterns
frontend-builder - Accessible React components
testing-strategist - Accessibility testing

External:

Build for everyone. ♿

Weekly Installs

Repository

daffy0208/ai-de…tandards

GitHub Stars

First Seen

Jan 1, 1970

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

111,800 周安装