accessibility
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAccessibility (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 Decide | Claude 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%的问题)
- Semantic HTML — The foundation of all accessibility
- Keyboard navigation — Every interactive element works without a mouse
- Color contrast — Text is readable against its background
- Form labels — Every input has a visible, linked label
- Image alt text — Every meaningful image has a description
- 语义化HTML —— 所有无障碍访问的基础
- 键盘导航 —— 所有交互元素无需鼠标即可正常工作
- 色彩对比度 —— 文本在背景上清晰可读
- 表单标签 —— 每个输入框都有可见的关联标签
- 图片替代文本 —— 每张有意义的图片都有描述
Tier 2: Add Next (After Launch)
第二层级:上线后添加
- Focus management — Modals trap focus, focus returns on close
- Error messages — Connected to inputs, announced by screen readers
- Skip navigation — Link to skip to main content
- Reduced motion — Respect user's motion preferences
- 焦点管理 —— 模态框锁定焦点,关闭后返回原焦点
- 错误提示 —— 与输入框关联,可被屏幕阅读器读取
- 跳过导航链接 —— 可直接跳转到主内容的链接
- 减少动画 —— 尊重用户的动画偏好设置
Tier 3: Polish (After Product-Market Fit)
第三层级:优化完善(产品-市场匹配后)
- Full ARIA patterns — Custom components (tabs, menus, date pickers)
- Screen reader testing — Test full flows with VoiceOver/NVDA
- Color blindness — Don't rely on color alone to convey information
- 完整ARIA模式 —— 自定义组件(标签页、菜单、日期选择器)
- 屏幕阅读器测试 —— 使用VoiceOver/NVDA测试完整流程
- 色盲适配 —— 不要仅依赖颜色传递信息
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 modalsKeyboard 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 elementColor Contrast
色彩对比度
| Element | Minimum Contrast Ratio |
|---|---|
| Body text | 4.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 checkerForm 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-describedbyTier 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 usersTesting 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 automaticallyDeeper 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
常见错误
| Mistake | Fix |
|---|---|
Adding | Never remove focus indicators. Style them instead. |
Using | Use semantic HTML elements. Buttons are |
| Placeholder as label | Always use a visible |
| Ignoring keyboard users | Test without a mouse. If you can't complete the flow, keyboard users can't either. |
| Bolting on ARIA to fix bad HTML | Fix the HTML first. ARIA is a repair tool, not a substitute. |
| Waiting until "later" to care | Build semantic HTML from day one. It's free and prevents 80% of issues. |
| 错误 | 修复方案 |
|---|---|
添加 | 永远不要移除焦点指示器,而是对其进行样式定制。 |
所有元素都用 | 使用语义化HTML元素。按钮要用 |
| 用占位符作为标签 | 始终使用可见的 |
| 忽略键盘用户 | 脱离鼠标进行测试。如果你无法完成流程,键盘用户也做不到。 |
| 用ARIA修补糟糕的HTML | 先修复HTML。ARIA是修复工具,而非替代品。 |
| 等到“以后”再重视无障碍访问 | 从第一天就使用语义化HTML构建应用。这无需额外成本,还能避免80%的问题。 |