accessibility

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Accessibility (a11y)

无障碍访问(a11y)

Accessibility is not optional — it's a quality attribute like performance or security. The good news: if you build with correct HTML from the start, you get 80% of accessibility for free. This skill tells you what to prioritize and what to hand to Claude Code.
无障碍访问并非可选功能——它是与性能、安全同级的质量属性。好消息是:如果从一开始就使用正确的HTML构建应用,你就能免费获得80%的无障碍访问能力。本技能会告诉你需要优先处理的内容,以及哪些工作可以交给Claude Code完成。

What You Decide vs. What AI Implements

由你决策 vs 由AI实现

You DecideClaude Code Implements
"Our app must be keyboard-navigable"Proper focus management, tab order, keyboard handlers
"All images need descriptions"Alt text on every image
"Forms must have clear error messages"Linked labels, aria-describedby, validation messages
"We support screen readers"Semantic HTML, ARIA roles, live regions
Rule: You set the standard. Claude Code does the implementation. Your job is to test it.

由你决策Claude Code 实现
"我们的应用必须支持键盘导航"正确的焦点管理、Tab键顺序、键盘事件处理程序
"所有图片都需要描述"为每张图片添加替代文本(Alt text)
"表单必须包含清晰的错误提示"关联标签、aria-describedby属性、验证提示
"我们要支持屏幕阅读器"语义化HTML、ARIA角色、实时区域
规则: 你设定标准,Claude Code负责实现。你的工作是进行测试。

Priority Order (What Gives You the Most Value)

优先级排序(价值最大化)

Don't try to achieve WCAG AAA compliance on day one. Start with the highest-impact wins:
不要试图在第一天就达到WCAG AAA级合规标准。从影响力最大的工作开始:

Tier 1: Start Here (Covers 80% of Issues)

第一层级:从这里开始(解决80%的问题)

  1. Semantic HTML — The foundation of all accessibility
  2. Keyboard navigation — Every interactive element works without a mouse
  3. Color contrast — Text is readable against its background
  4. Form labels — Every input has a visible, linked label
  5. Image alt text — Every meaningful image has a description
  1. 语义化HTML —— 所有无障碍访问的基础
  2. 键盘导航 —— 所有交互元素无需鼠标即可正常工作
  3. 色彩对比度 —— 文本在背景上清晰可读
  4. 表单标签 —— 每个输入框都有可见的关联标签
  5. 图片替代文本 —— 每张有意义的图片都有描述

Tier 2: Add Next (After Launch)

第二层级:上线后添加

  1. Focus management — Modals trap focus, focus returns on close
  2. Error messages — Connected to inputs, announced by screen readers
  3. Skip navigation — Link to skip to main content
  4. Reduced motion — Respect user's motion preferences
  1. 焦点管理 —— 模态框锁定焦点,关闭后返回原焦点
  2. 错误提示 —— 与输入框关联,可被屏幕阅读器读取
  3. 跳过导航链接 —— 可直接跳转到主内容的链接
  4. 减少动画 —— 尊重用户的动画偏好设置

Tier 3: Polish (After Product-Market Fit)

第三层级:优化完善(产品-市场匹配后)

  1. Full ARIA patterns — Custom components (tabs, menus, date pickers)
  2. Screen reader testing — Test full flows with VoiceOver/NVDA
  3. Color blindness — Don't rely on color alone to convey information

  1. 完整ARIA模式 —— 自定义组件(标签页、菜单、日期选择器)
  2. 屏幕阅读器测试 —— 使用VoiceOver/NVDA测试完整流程
  3. 色盲适配 —— 不要仅依赖颜色传递信息

Tier 1: Implementation

第一层级:实现方案

Semantic HTML

语义化HTML

Tell AI:
Audit and fix HTML semantics across the app:
- Use <button> for actions, <a> for navigation (never the reverse)
- Use <nav>, <main>, <aside>, <header>, <footer>, <article>, <section> for page structure
- Use <h1>-<h6> in order (no skipped levels, never used just for styling)
- Use <label> linked to every form input
- Use <ul>/<ol> for lists
- Use <table> with proper <th> headers for tabular data
- Use <dialog> for modals
告知AI:
Audit and fix HTML semantics across the app:
- Use <button> for actions, <a> for navigation (never the reverse)
- Use <nav>, <main>, <aside>, <header>, <footer>, <article>, <section> for page structure
- Use <h1>-<h6> in order (no skipped levels, never used just for styling)
- Use <label> linked to every form input
- Use <ul>/<ol> for lists
- Use <table> with proper <th> headers for tabular data
- Use <dialog> for modals

Keyboard Navigation

键盘导航

Tell AI:
Ensure full keyboard accessibility:
- Every interactive element (button, link, input, select) must be reachable with Tab
- Every interactive element must be activatable with Enter or Space
- Tab order must follow visual reading order
- Focus states must be clearly visible (not just outline: none)
- Modals must trap focus inside and return focus to the trigger on close
- Add a "Skip to main content" link as the first focusable element
告知AI:
Ensure full keyboard accessibility:
- Every interactive element (button, link, input, select) must be reachable with Tab
- Every interactive element must be activatable with Enter or Space
- Tab order must follow visual reading order
- Focus states must be clearly visible (not just outline: none)
- Modals must trap focus inside and return focus to the trigger on close
- Add a "Skip to main content" link as the first focusable element

Color Contrast

色彩对比度

ElementMinimum Contrast Ratio
Body text4.5:1 against background
Large text (18px+ or 14px+ bold)3:1
UI components (borders, icons)3:1
Tell AI:
Check and fix color contrast across the app:
- Verify all text meets WCAG AA contrast ratios (4.5:1 for body, 3:1 for large text)
- Verify UI elements (borders, icons, focus rings) meet 3:1 contrast
- Don't rely on color alone — add icons, patterns, or text labels alongside color indicators
- Test with the browser's built-in contrast checker
元素最低对比度
正文文本与背景对比度4.5:1
大文本(18px及以上或14px及以上加粗)3:1
UI组件(边框、图标)3:1
告知AI:
Check and fix color contrast across the app:
- Verify all text meets WCAG AA contrast ratios (4.5:1 for body, 3:1 for large text)
- Verify UI elements (borders, icons, focus rings) meet 3:1 contrast
- Don't rely on color alone — add icons, patterns, or text labels alongside color indicators
- Test with the browser's built-in contrast checker

Form Labels and Alt Text

表单标签与图片替代文本

Tell AI:
Fix form accessibility:
- Every input must have a visible <label> linked via for="id" attribute
- Placeholder text is NOT a label (it disappears on focus)
- Required fields: add visual indicator AND aria-required="true"
- Add autocomplete attributes for personal data: autocomplete="email", "name", etc.

Fix image accessibility:
- Every meaningful image needs descriptive alt text (max 125 chars)
- Decorative images need alt="" (empty alt, not missing alt)
- Charts and diagrams need a text description nearby or via aria-describedby

告知AI:
Fix form accessibility:
- Every input must have a visible <label> linked via for="id" attribute
- Placeholder text is NOT a label (it disappears on focus)
- Required fields: add visual indicator AND aria-required="true"
- Add autocomplete attributes for personal data: autocomplete="email", "name", etc.

Fix image accessibility:
- Every meaningful image needs descriptive alt text (max 125 chars)
- Decorative images need alt="" (empty alt, not missing alt)
- Charts and diagrams need a text description nearby or via aria-describedby

Tier 2: After Launch

第二层级:上线后优化

Focus Management and Error Messages

焦点管理与错误提示

Tell AI:
Improve focus management and error handling:
- When a modal opens, move focus to the first interactive element inside
- When a modal closes, return focus to the button that opened it
- Trap focus inside modals (Tab shouldn't escape to the background)
- Connect error messages to inputs via aria-describedby
- When a form has errors, add aria-invalid="true" to invalid fields
- Announce dynamic content changes with aria-live="polite" (status messages) or aria-live="assertive" (errors)
告知AI:
Improve focus management and error handling:
- When a modal opens, move focus to the first interactive element inside
- When a modal closes, return focus to the button that opened it
- Trap focus inside modals (Tab shouldn't escape to the background)
- Connect error messages to inputs via aria-describedby
- When a form has errors, add aria-invalid="true" to invalid fields
- Announce dynamic content changes with aria-live="polite" (status messages) or aria-live="assertive" (errors)

Reduced Motion

减少动画

Tell AI:
Respect user motion preferences:
- Add a CSS media query: @media (prefers-reduced-motion: reduce) { * { animation: none !important; } }
- Disable autoplay on videos and carousels when reduced motion is preferred
- Keep transitions under 200ms or remove them for reduced-motion users

告知AI:
Respect user motion preferences:
- Add a CSS media query: @media (prefers-reduced-motion: reduce) { * { animation: none !important; } }
- Disable autoplay on videos and carousels when reduced motion is preferred
- Keep transitions under 200ms or remove them for reduced-motion users

Testing Checklist

测试清单

Run through these checks before each release:
每次发布前完成以下检查:

Quick Test (5 minutes)

快速测试(5分钟)

  • Put your mouse away. Navigate the entire signup → core action flow with keyboard only.
  • Can you reach every button, link, and input with Tab?
  • Can you see where focus is on every element?
  • Can you activate every button with Enter or Space?
  • Can you escape every modal with Escape?
  • 放下鼠标,仅使用键盘完成从注册到核心操作的完整流程。
  • 能否通过Tab键到达所有按钮、链接和输入框?
  • 能否看到每个元素的焦点位置?
  • 能否通过Enter或Space键激活所有按钮?
  • 能否通过Escape键关闭所有模态框?

Automated Test

自动化测试

Tell AI:
Run an accessibility audit:
- Run axe-core or Lighthouse accessibility audit on our main pages
- Report all violations grouped by severity (critical, serious, moderate, minor)
- Fix all critical and serious violations
- Add accessibility checks to our CI pipeline so new issues are caught automatically
告知AI:
Run an accessibility audit:
- Run axe-core or Lighthouse accessibility audit on our main pages
- Report all violations grouped by severity (critical, serious, moderate, minor)
- Fix all critical and serious violations
- Add accessibility checks to our CI pipeline so new issues are caught automatically

Deeper Test (When Ready)

深度测试(准备就绪时)

  • Test with VoiceOver (Mac: Cmd+F5) or NVDA (Windows, free)
  • Test at 200% browser zoom — no content loss or horizontal scrolling
  • Test with a color blindness simulator browser extension
  • Verify all videos have captions

  • 使用VoiceOver(Mac:Cmd+F5)或NVDA(Windows,免费)进行测试
  • 将浏览器缩放至200%测试——无内容丢失或横向滚动
  • 使用色盲模拟器浏览器扩展进行测试
  • 验证所有视频都配有字幕

Common Mistakes

常见错误

MistakeFix
Adding
outline: none
to make focus "look clean"
Never remove focus indicators. Style them instead.
Using
<div>
for everything
Use semantic HTML elements. Buttons are
<button>
, not
<div onclick>
.
Placeholder as labelAlways use a visible
<label>
. Placeholders are hints, not labels.
Ignoring keyboard usersTest without a mouse. If you can't complete the flow, keyboard users can't either.
Bolting on ARIA to fix bad HTMLFix the HTML first. ARIA is a repair tool, not a substitute.
Waiting until "later" to careBuild semantic HTML from day one. It's free and prevents 80% of issues.
错误修复方案
添加
outline: none
让焦点“看起来更整洁”
永远不要移除焦点指示器,而是对其进行样式定制。
所有元素都用
<div>
使用语义化HTML元素。按钮要用
<button>
,而非
<div onclick>
用占位符作为标签始终使用可见的
<label>
。占位符是提示信息,而非标签。
忽略键盘用户脱离鼠标进行测试。如果你无法完成流程,键盘用户也做不到。
用ARIA修补糟糕的HTML先修复HTML。ARIA是修复工具,而非替代品。
等到“以后”再重视无障碍访问从第一天就使用语义化HTML构建应用。这无需额外成本,还能避免80%的问题。