Web无障碍性(a11y)开发指南：WCAG 2.1原则、Lighthouse审核与代码实践

accessibility by davila7/claude-code-templates

185 周安装量

24,200 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/davila7/claude-code-templates --skill accessibility

开发代码规范用户体验

🇨🇳中文介绍

无障碍性 (a11y)

基于 WCAG 2.1 和 Lighthouse 无障碍性审核的全面无障碍性指南。目标：让所有用户（包括残障人士）都能使用内容。

WCAG 原则：POUR

原则	描述
P 可感知性	内容可以通过不同的感官感知
O 可操作性	所有用户都可以操作界面
U 可理解性	内容和界面易于理解
R 健壮性	内容可与辅助技术配合使用

一致性级别

级别	要求	目标
A	最低无障碍性	必须通过
AA	标准合规性	应该通过（许多司法管辖区的法律要求）

广告位招租

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

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

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

879,700 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

286,600 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

231,000 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

159,700 周安装

<!-- ❌ 缺少 alt -->
<img src="chart.png">

<!-- ✅ 描述性 alt -->
<img src="chart.png" alt="Bar chart showing 40% increase in Q3 sales">

<!-- ✅ 装饰性图像（空 alt） -->
<img src="decorative-border.png" alt="" role="presentation">

<!-- ✅ 具有较长描述的复杂图像 -->
<figure>
  <img src="infographic.png" alt="2024 market trends infographic" 
       aria-describedby="infographic-desc">
  <figcaption id="infographic-desc">
    <!-- 详细描述 -->
  </figcaption>
</figure>

<!-- ❌ 无可访问名称 -->
<button><svg><!-- menu icon --></svg></button>

<!-- ✅ 使用 aria-label -->
<button aria-label="Open menu">
  <svg aria-hidden="true"><!-- menu icon --></svg>
</button>

<!-- ✅ 使用视觉隐藏文本 -->
<button>
  <svg aria-hidden="true"><!-- menu icon --></svg>
  <span class="visually-hidden">Open menu</span>
</button>

文本大小	AA 最低要求	AAA 增强要求
普通文本 (< 18px / < 14px 粗体)	4.5:1	7:1
大文本 (≥ 18px / ≥ 14px 粗体)	3:1	4.5:1
UI 组件和图形	3:1	3:1

/* ❌ 低对比度 (2.5:1) */
.low-contrast {
  color: #999;
  background: #fff;
}

/* ✅ 足够对比度 (7:1) */
.high-contrast {
  color: #333;
  background: #fff;
}

/* ✅ 焦点状态也需要对比度 */
:focus-visible {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

<!-- ❌ 仅颜色指示错误 -->
<input class="error-border">
<style>.error-border { border-color: red; }</style>

<!-- ✅ 颜色 + 图标 + 文本 -->
<div class="field-error">
  <input aria-invalid="true" aria-describedby="email-error">
  <span id="email-error" class="error-message">
    <svg aria-hidden="true"><!-- error icon --></svg>
    Please enter a valid email address
  </span>
</div>

<!-- 带字幕的视频 -->
<video controls>
  <source src="video.mp4" type="video/mp4">
  <track kind="captions" src="captions.vtt" srclang="en" label="English" default>
  <track kind="descriptions" src="descriptions.vtt" srclang="en" label="Descriptions">
</video>

<!-- 带文字稿的音频 -->
<audio controls>
  <source src="podcast.mp3" type="audio/mp3">
</audio>
<details>
  <summary>Transcript</summary>
  <p>Full transcript text...</p>
</details>

// ❌ 仅处理点击
element.addEventListener('click', handleAction);

// ✅ 处理点击和键盘
element.addEventListener('click', handleAction);
element.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    handleAction();
  }
});

// 模态框焦点管理
function openModal(modal) {
  const focusableElements = modal.querySelectorAll(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const firstElement = focusableElements[0];
  const lastElement = focusableElements[focusableElements.length - 1];
  
  // 将焦点限制在模态框内
  modal.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === firstElement) {
        e.preventDefault();
        lastElement.focus();
      } else if (!e.shiftKey && document.activeElement === lastElement) {
        e.preventDefault();
        firstElement.focus();
      }
    }
    if (e.key === 'Escape') {
      closeModal();
    }
  });
  
  firstElement.focus();
}

/* ❌ 切勿移除焦点轮廓 */
*:focus { outline: none; }

/* ✅ 使用 :focus-visible 仅针对键盘焦点 */
:focus {
  outline: none;
}

:focus-visible {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

/* ✅ 或自定义焦点样式 */
button:focus-visible {
  box-shadow: 0 0 0 3px rgba(0, 95, 204, 0.5);
}

<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>
  <header><!-- navigation --></header>
  <main id="main-content" tabindex="-1">
    <!-- main content -->
  </main>
</body>



.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: #fff;
  padding: 8px 16px;
  z-index: 100;
}

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

// 允许用户延长时间限制
function showSessionWarning() {
  const modal = createModal({
    title: 'Session Expiring',
    content: 'Your session will expire in 2 minutes.',
    actions: [
      { label: 'Extend session', action: extendSession },
      { label: 'Log out', action: logout }
    ],
    timeout: 120000 // 2 分钟响应时间
  });
}

/* 尊重减少动效偏好 */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

<!-- ❌ 无标签关联 -->
<input type="email" placeholder="Email">

<!-- ✅ 显式标签 -->
<label for="email">Email address</label>
<input type="email" id="email" name="email" 
       autocomplete="email" required>

<!-- ✅ 隐式标签 -->
<label>
  Email address
  <input type="email" name="email" autocomplete="email" required>
</label>

<!-- ✅ 带说明 -->
<label for="password">Password</label>
<input type="password" id="password" 
       aria-describedby="password-requirements">
<p id="password-requirements">
  Must be at least 8 characters with one number.
</p>

<!-- 向屏幕阅读器宣布错误 -->
<form novalidate>
  <div class="field" aria-live="polite">
    <label for="email">Email</label>
    <input type="email" id="email" 
           aria-invalid="true"
           aria-describedby="email-error">
    <p id="email-error" class="error" role="alert">
      Please enter a valid email address (e.g., name@example.com)
    </p>
  </div>
</form>



// 提交时将焦点置于第一个错误上
form.addEventListener('submit', (e) => {
  const firstError = form.querySelector('[aria-invalid="true"]');
  if (firstError) {
    e.preventDefault();
    firstError.focus();
    
    // 宣布错误摘要
    const errorSummary = document.getElementById('error-summary');
    errorSummary.textContent = `${errors.length} errors found. Please fix them and try again.`;
    errorSummary.focus();
  }
});

<!-- ❌ 重复的 ID -->
<div id="content">...</div>
<div id="content">...</div>

<!-- ❌ 无效的嵌套 -->
<a href="/"><button>Click</button></a>

<!-- ✅ 唯一的 ID -->
<div id="main-content">...</div>
<div id="sidebar-content">...</div>

<!-- ✅ 正确的嵌套 -->
<a href="/" class="button-link">Click</a>

<!-- ❌ 在 div 上使用 ARIA role -->
<div role="button" tabindex="0">Click me</div>

<!-- ✅ 原生按钮 -->
<button>Click me</button>

<!-- ❌ ARIA 复选框 -->
<div role="checkbox" aria-checked="false">Option</div>

<!-- ✅ 原生复选框 -->
<label><input type="checkbox"> Option</label>

<!-- 自定义标签页组件 -->
<div role="tablist" aria-label="Product information">
  <button role="tab" id="tab-1" aria-selected="true" 
          aria-controls="panel-1">Description</button>
  <button role="tab" id="tab-2" aria-selected="false" 
          aria-controls="panel-2" tabindex="-1">Reviews</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
  <!-- 面板内容 -->
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
  <!-- 面板内容 -->
</div>

<!-- 状态更新 -->
<div aria-live="polite" aria-atomic="true" class="status">
  <!-- 内容更新会向屏幕阅读器宣布 -->
</div>

<!-- 紧急警报 -->
<div role="alert" aria-live="assertive">
  <!-- 中断当前宣布 -->
</div>



// 宣布动态内容变化
function showNotification(message, type = 'polite') {
  const container = document.getElementById(`${type}-announcer`);
  container.textContent = ''; // 先清空
  requestAnimationFrame(() => {
    container.textContent = message;
  });
}

键盘导航： 用 Tab 键遍历整个页面，使用 Enter/Space 键激活
屏幕阅读器： 使用 VoiceOver (Mac)、NVDA (Windows) 或 TalkBack (Android) 测试
缩放： 内容在 200% 缩放下仍可使用
高对比度： 使用 Windows 高对比度模式测试
减少动效： 使用 prefers-reduced-motion: reduce 测试
焦点顺序： 逻辑合理且遵循视觉顺序

操作	VoiceOver (Mac)	NVDA (Windows)
启动/停止	⌘ + F5	Ctrl + Alt + N
下一项	VO + →	↓
上一项	VO + ←	↑
激活	VO + Space	Enter
标题列表	VO + U，然后方向键	H / Shift + H
链接列表	VO + U	K / Shift + K

🇺🇸English

Accessibility (a11y)

Comprehensive accessibility guidelines based on WCAG 2.1 and Lighthouse accessibility audits. Goal: make content usable by everyone, including people with disabilities.

WCAG Principles: POUR

Principle	Description
P erceivable	Content can be perceived through different senses
O perable	Interface can be operated by all users
U nderstandable	Content and interface are understandable
R obust	Content works with assistive technologies

Conformance levels

Level	Requirement	Target
A	Minimum accessibility	Must pass
AA	Standard compliance	Should pass (legal requirement in many jurisdictions)
AAA	Enhanced accessibility	Nice to have

Perceivable

Text alternatives (1.1)

Images require alt text:

<!-- ❌ Missing alt -->
<img src="chart.png">

<!-- ✅ Descriptive alt -->
<img src="chart.png" alt="Bar chart showing 40% increase in Q3 sales">

<!-- ✅ Decorative image (empty alt) -->
<img src="decorative-border.png" alt="" role="presentation">

<!-- ✅ Complex image with longer description -->
<figure>
  <img src="infographic.png" alt="2024 market trends infographic" 
       aria-describedby="infographic-desc">
  <figcaption id="infographic-desc">
    <!-- Detailed description -->
  </figcaption>
</figure>

Icon buttons need accessible names:

<!-- ❌ No accessible name -->
<button><svg><!-- menu icon --></svg></button>

<!-- ✅ Using aria-label -->
<button aria-label="Open menu">
  <svg aria-hidden="true"><!-- menu icon --></svg>
</button>

<!-- ✅ Using visually hidden text -->
<button>
  <svg aria-hidden="true"><!-- menu icon --></svg>
  <span class="visually-hidden">Open menu</span>
</button>

Visually hidden class:

.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Color contrast (1.4.3, 1.4.6)

Text Size	AA minimum	AAA enhanced
Normal text (< 18px / < 14px bold)	4.5:1	7:1
Large text (≥ 18px / ≥ 14px bold)	3:1	4.5:1
UI components & graphics	3:1	3:1

/* ❌ Low contrast (2.5:1) */
.low-contrast {
  color: #999;
  background: #fff;
}

/* ✅ Sufficient contrast (7:1) */
.high-contrast {
  color: #333;
  background: #fff;
}

/* ✅ Focus states need contrast too */
:focus-visible {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

Don't rely on color alone:

<!-- ❌ Only color indicates error -->
<input class="error-border">
<style>.error-border { border-color: red; }</style>

<!-- ✅ Color + icon + text -->
<div class="field-error">
  <input aria-invalid="true" aria-describedby="email-error">
  <span id="email-error" class="error-message">
    <svg aria-hidden="true"><!-- error icon --></svg>
    Please enter a valid email address
  </span>
</div>

Media alternatives (1.2)

<!-- Video with captions -->
<video controls>
  <source src="video.mp4" type="video/mp4">
  <track kind="captions" src="captions.vtt" srclang="en" label="English" default>
  <track kind="descriptions" src="descriptions.vtt" srclang="en" label="Descriptions">
</video>

<!-- Audio with transcript -->
<audio controls>
  <source src="podcast.mp3" type="audio/mp3">
</audio>
<details>
  <summary>Transcript</summary>
  <p>Full transcript text...</p>
</details>

Operable

Keyboard accessible (2.1)

All functionality must be keyboard accessible:

// ❌ Only handles click
element.addEventListener('click', handleAction);

// ✅ Handles both click and keyboard
element.addEventListener('click', handleAction);
element.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    handleAction();
  }
});

No keyboard traps:

// Modal focus management
function openModal(modal) {
  const focusableElements = modal.querySelectorAll(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const firstElement = focusableElements[0];
  const lastElement = focusableElements[focusableElements.length - 1];
  
  // Trap focus within modal
  modal.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === firstElement) {
        e.preventDefault();
        lastElement.focus();
      } else if (!e.shiftKey && document.activeElement === lastElement) {
        e.preventDefault();
        firstElement.focus();
      }
    }
    if (e.key === 'Escape') {
      closeModal();
    }
  });
  
  firstElement.focus();
}

Focus visible (2.4.7)

/* ❌ Never remove focus outlines */
*:focus { outline: none; }

/* ✅ Use :focus-visible for keyboard-only focus */
:focus {
  outline: none;
}

:focus-visible {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

/* ✅ Or custom focus styles */
button:focus-visible {
  box-shadow: 0 0 0 3px rgba(0, 95, 204, 0.5);
}

Skip links (2.4.1)

<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>
  <header><!-- navigation --></header>
  <main id="main-content" tabindex="-1">
    <!-- main content -->
  </main>
</body>



.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: #fff;
  padding: 8px 16px;
  z-index: 100;
}

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

Timing (2.2)

// Allow users to extend time limits
function showSessionWarning() {
  const modal = createModal({
    title: 'Session Expiring',
    content: 'Your session will expire in 2 minutes.',
    actions: [
      { label: 'Extend session', action: extendSession },
      { label: 'Log out', action: logout }
    ],
    timeout: 120000 // 2 minutes to respond
  });
}

Motion (2.3)

/* Respect reduced motion preference */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Understandable

Page language (3.1.1)

<!-- ❌ No language specified -->
<html>

<!-- ✅ Language specified -->
<html lang="en">

<!-- ✅ Language changes within page -->
<p>The French word for hello is <span lang="fr">bonjour</span>.</p>

Consistent navigation (3.2.3)

<!-- Navigation should be consistent across pages -->
<nav aria-label="Main">
  <ul>
    <li><a href="/" aria-current="page">Home</a></li>
    <li><a href="/products">Products</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

Form labels (3.3.2)

<!-- ❌ No label association -->
<input type="email" placeholder="Email">

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

<!-- ✅ Implicit label -->
<label>
  Email address
  <input type="email" name="email" autocomplete="email" required>
</label>

<!-- ✅ With instructions -->
<label for="password">Password</label>
<input type="password" id="password" 
       aria-describedby="password-requirements">
<p id="password-requirements">
  Must be at least 8 characters with one number.
</p>

Error handling (3.3.1, 3.3.3)

<!-- Announce errors to screen readers -->
<form novalidate>
  <div class="field" aria-live="polite">
    <label for="email">Email</label>
    <input type="email" id="email" 
           aria-invalid="true"
           aria-describedby="email-error">
    <p id="email-error" class="error" role="alert">
      Please enter a valid email address (e.g., name@example.com)
    </p>
  </div>
</form>



// Focus first error on submit
form.addEventListener('submit', (e) => {
  const firstError = form.querySelector('[aria-invalid="true"]');
  if (firstError) {
    e.preventDefault();
    firstError.focus();
    
    // Announce error summary
    const errorSummary = document.getElementById('error-summary');
    errorSummary.textContent = `${errors.length} errors found. Please fix them and try again.`;
    errorSummary.focus();
  }
});

Robust

Valid HTML (4.1.1)

<!-- ❌ Duplicate IDs -->
<div id="content">...</div>
<div id="content">...</div>

<!-- ❌ Invalid nesting -->
<a href="/"><button>Click</button></a>

<!-- ✅ Unique IDs -->
<div id="main-content">...</div>
<div id="sidebar-content">...</div>

<!-- ✅ Proper nesting -->
<a href="/" class="button-link">Click</a>

ARIA usage (4.1.2)

Prefer native elements:

<!-- ❌ ARIA role on div -->
<div role="button" tabindex="0">Click me</div>

<!-- ✅ Native button -->
<button>Click me</button>

<!-- ❌ ARIA checkbox -->
<div role="checkbox" aria-checked="false">Option</div>

<!-- ✅ Native checkbox -->
<label><input type="checkbox"> Option</label>

When ARIA is needed:

<!-- Custom tabs component -->
<div role="tablist" aria-label="Product information">
  <button role="tab" id="tab-1" aria-selected="true" 
          aria-controls="panel-1">Description</button>
  <button role="tab" id="tab-2" aria-selected="false" 
          aria-controls="panel-2" tabindex="-1">Reviews</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
  <!-- Panel content -->
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
  <!-- Panel content -->
</div>

Live regions (4.1.3)

<!-- Status updates -->
<div aria-live="polite" aria-atomic="true" class="status">
  <!-- Content updates announced to screen readers -->
</div>

<!-- Urgent alerts -->
<div role="alert" aria-live="assertive">
  <!-- Interrupts current announcement -->
</div>



// Announce dynamic content changes
function showNotification(message, type = 'polite') {
  const container = document.getElementById(`${type}-announcer`);
  container.textContent = ''; // Clear first
  requestAnimationFrame(() => {
    container.textContent = message;
  });
}

Testing checklist

Automated testing

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

# axe-core
npm install @axe-core/cli -g
axe https://example.com

Manual testing

Keyboard navigation: Tab through entire page, use Enter/Space to activate
Screen reader: Test with VoiceOver (Mac), NVDA (Windows), or TalkBack (Android)
Zoom: Content usable at 200% zoom
High contrast: Test with Windows High Contrast Mode
Reduced motion: Test with prefers-reduced-motion: reduce
Focus order: Logical and follows visual order

Screen reader commands

Action	VoiceOver (Mac)	NVDA (Windows)
Start/Stop	⌘ + F5	Ctrl + Alt + N
Next item	VO + →	↓
Previous item	VO + ←	↑
Activate	VO + Space	Enter
Headings list	VO + U, then arrows	H / Shift + H
Links list	VO + U	K / Shift + K

Common issues by impact

Critical (fix immediately)

Missing form labels
Missing image alt text
Insufficient color contrast
Keyboard traps
No focus indicators

Serious (fix before launch)

Missing page language
Missing heading structure
Non-descriptive link text
Auto-playing media
Missing skip links

Moderate (fix soon)

Missing ARIA labels on icons
Inconsistent navigation
Missing error identification
Timing without controls
Missing landmark regions

References

Weekly Installs

139

Repository

davila7/claude-…emplates

GitHub Stars

23.5K

First Seen

Feb 1, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex135

opencode134

github-copilot132

gemini-cli130

kimi-cli128

amp127

Web无障碍性(a11y)开发指南：WCAG 2.1原则、Lighthouse审核与代码实践

🇨🇳中文介绍

无障碍性 (a11y)

WCAG 原则：POUR

一致性级别

相关 Skills

可感知性

文本替代方案 (1.1)

颜色对比度 (1.4.3, 1.4.6)

媒体替代方案 (1.2)

可操作性

键盘可访问性 (2.1)

焦点可见性 (2.4.7)

跳过链接 (2.4.1)

定时 (2.2)

动效 (2.3)

可理解性

页面语言 (3.1.1)

一致的导航 (3.2.3)

表单标签 (3.3.2)

错误处理 (3.3.1, 3.3.3)

健壮性

有效的 HTML (4.1.1)

ARIA 使用 (4.1.2)

实时区域 (4.1.3)

测试清单

自动化测试

手动测试

屏幕阅读器命令

按影响程度划分的常见问题

严重（立即修复）

重大（发布前修复）

中等（尽快修复）

参考资料