Back to Details

a11y-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Accessibility Best Practices

无障碍设计最佳实践

This skill covers comprehensive accessibility patterns for building inclusive interfaces — from prevention to identification to remediation. It addresses the most common accessibility issues found on the web (based on WebAIM Million reports showing 95% of sites fail WCAG AA).
本文涵盖了构建包容性界面的综合无障碍模式——从预防、识别到修复全流程。它针对网页上最常见的无障碍问题（根据WebAIM Million报告显示，95%的网站未达到WCAG AA标准）。

Use-When

适用场景

This skill activates when:
  • Agent builds new UI components (buttons, forms, modals, menus)
  • Agent creates page layouts or content structures
  • Agent adds images, media, or interactive elements
  • Agent audits existing code for accessibility issues
  • Agent fixes accessibility bugs or violations
  • Agent writes tests that should verify accessibility
当以下情况触发此技能：
  • Agent构建新的UI组件（按钮、表单、模态框、菜单）
  • Agent创建页面布局或内容结构
  • Agent添加图片、媒体或交互元素
  • Agent审计现有代码的无障碍问题
  • Agent修复无障碍缺陷或违规问题
  • Agent编写用于验证无障碍性的测试

Core Rules

核心规则

Prevention (Building Accessible)

预防（构建无障碍界面）

  • ALWAYS ensure minimum 4.5:1 contrast ratio for normal text (3:1 for large text)
  • ALWAYS use semantic HTML elements over custom divs
  • ALWAYS provide explicit, visible labels for all form inputs
  • ALWAYS make all interactive elements keyboard accessible
  • ALWAYS include visible focus indicators
  • ALWAYS use proper heading hierarchy (no skipping levels)
  • ALWAYS provide alt text for meaningful images
  • ALWAYS use buttons for actions, links for navigation
  • PREFER semantic HTML over ARIA (ARIA is a supplement, not a replacement)
  • 始终确保普通文本的对比度至少为4.5:1（大文本为3:1）
  • 始终使用语义化HTML元素而非自定义div
  • 始终为所有表单输入提供明确可见的标签
  • 始终确保所有交互元素支持键盘操作
  • 始终包含可见的焦点指示器
  • 始终使用正确的标题层级（不可跳过层级）
  • 始终为有意义的图片提供替代文本（alt text）
  • 始终使用按钮执行操作，使用链接进行导航
  • 优先使用语义化HTML而非ARIA（ARIA是补充而非替代方案）

Identification (Finding Issues)

识别（发现问题）

  • ALWAYS test with automated tools (axe, WAVE) to catch common issues
  • ALWAYS test with keyboard-only navigation
  • ALWAYS test with a screen reader (NVDA, VoiceOver)
  • REMEMBER: Automated tools catch only 30-57% of accessibility issues
  • 始终使用自动化工具（axe、WAVE）检测常见问题
  • 始终仅通过键盘进行导航测试
  • 始终使用屏幕阅读器（NVDA、VoiceOver）进行测试
  • 注意：自动化工具仅能检测30-57%的无障碍问题

Remediation (Fixing Issues)

修复（解决问题）

  • NEVER rely on color alone to convey information
  • NEVER use placeholder text as a replacement for labels
  • NEVER have empty links or buttons
  • NEVER use generic text like "click here" for links
  • NEVER create keyboard traps (focus must be escapable)
  • 切勿仅依赖颜色传递信息
  • 切勿使用占位符文本替代标签
  • 切勿存在空链接或空按钮
  • 切勿为链接使用“点击此处”这类通用文本
  • 切勿创建键盘陷阱（焦点必须可移出）

Common Agent Mistakes

Agent常见错误

  • Using divs with onClick instead of buttons
  • Adding role="button" to divs (still not keyboard accessible)
  • Using placeholder as the only label (disappears on focus)
  • Forgetting to associate error messages with form fields
  • Adding redundant ARIA to native HTML elements
  • Using aria-label when visible text would work
  • Creating heading hierarchies that skip levels (h1 → h3)
  • Making focus indicators invisible (outline: none without replacement)
  • Using color as the only indicator of state (need text/icon too)
  • Not providing way to escape modals/keyboard traps
  • 使用带onClick的div而非按钮
  • 为div添加role="button"（仍不支持键盘操作）
  • 仅使用占位符作为标签（获取焦点后会消失）
  • 忘记将错误消息与表单字段关联
  • 为原生HTML元素添加冗余的ARIA属性
  • 当可见文本可用时仍使用aria-label
  • 创建跳过层级的标题结构（如h1 → h3）
  • 隐藏焦点指示器（使用outline: none但未提供替代方案）
  • 仅使用颜色作为状态指示器（还需文本/图标辅助）
  • 未提供退出模态框/键盘陷阱的方式

Examples

示例

✅ Correct

✅ 正确示例

tsx
// Semantic elements with proper contrast
<button className="bg-slate-900 text-white focus-visible:ring-2">
  Submit
</button>

// Explicit form labels
<label htmlFor="email">Email address</label>
<input id="email" type="email" aria-describedby="email-hint" />
<p id="email-hint">We'll never share your email.</p>

// Image with alt text
<img src="chart.png" alt="Sales increased 25% from Q1 to Q2" />

// Proper heading hierarchy
<h1>Page Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>

// Skip link
<a href="#main" className="sr-only focus:not-sr-only">Skip to content</a>
<main id="main">
tsx
// Semantic elements with proper contrast
<button className="bg-slate-900 text-white focus-visible:ring-2">
  Submit
</button>

// Explicit form labels
<label htmlFor="email">Email address</label>
<input id="email" type="email" aria-describedby="email-hint" />
<p id="email-hint">We'll never share your email.</p>

// Image with alt text
<img src="chart.png" alt="Sales increased 25% from Q1 to Q2" />

// Proper heading hierarchy
<h1>Page Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>

// Skip link
<a href="#main" className="sr-only focus:not-sr-only">Skip to content</a>
<main id="main">

❌ Wrong

❌ 错误示例

tsx
// Using div as button (not keyboard accessible)
<div onClick={submit}>Submit</div>

// Placeholder only (invisible on focus)
<input placeholder="Enter email" />

// Missing alt text
<img src="photo.jpg" />

// Heading skip (h1 → h3)
<h1>Title</h1>
<h3>Subtitle</h3>

// Generic link text
<a href="/details">Click here</a> to learn more

// No focus indicator
<button className="outline-none">Action</button>
tsx
// Using div as button (not keyboard accessible)
<div onClick={submit}>Submit</div>

// Placeholder only (invisible on focus)
<input placeholder="Enter email" />

// Missing alt text
<img src="photo.jpg" />

// Heading skip (h1 → h3)
<h1>Title</h1>
<h3>Subtitle</h3>

// Generic link text
<a href="/details">Click here</a> to learn more

// No focus indicator
<button className="outline-none">Action</button>

Testing Overview

测试概述

Accessibility testing requires multiple approaches:
  1. Automated Testing - Catches ~30-57% of issues (contrast, labels, ARIA)
  2. Keyboard Testing - All interactions must work without a mouse
  3. Screen Reader Testing - Content must make sense when read aloud
Run validation on all changes to ensure no regressions.
无障碍测试需要多种方法结合：
  1. 自动化测试 - 可检测约30-57%的问题（对比度、标签、ARIA等）
  2. 键盘测试 - 所有交互必须无需鼠标即可完成
  3. 屏幕阅读器测试 - 内容朗读时需逻辑通顺
对所有变更进行验证，确保无障碍性不出现回归问题。

References

参考资料