accessibility-engineering
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAccessibility Engineering
无障碍工程
Overview
概述
Accessibility is not a polish step — it's a legal requirement in many jurisdictions, an engineering quality standard, and a prerequisite for shipping. This skill audits existing interfaces, triages the findings, and remediates verified violations. The goal is WCAG 2.2 AA compliance supported by automated tools and manual testing.
无障碍并非锦上添花的最后一步——在许多司法辖区,它是一项法律要求、一项工程质量标准,也是发布产品的前提。该 Skill 审计现有界面对发现的问题进行分诊,并修复经验证的违规问题。其目标是在自动化工具和手动测试的支持下达到 WCAG 2.2 AA 符合性。
When to Use
何时使用
- Before shipping a user-facing change that needs an accessibility audit
- When a11y issues are reported (e.g., "screen reader can't read this", "keyboard navigation broken")
- When auditing an existing interface for compliance
- When triaging axe-core or pa11y findings
- When remediating verified accessibility violations
Do NOT use for building new UI components from scratch; use for construction guidance. Do not use for backend-only changes, CLIs, or library code with no UI output.
frontend-ui-engineering- 在发布需要接受无障碍审计的面向用户的变更之前
- 当有人报告 a11y 问题时(例如,“屏幕阅读器无法读取此内容”“键盘导航失效”)
- 当需要审计现有界面的符合性时
- 当需要分诊 axe-core 或 pa11y 的审计结果时
- 当需要修复已确认的无障碍违规问题时
请勿用于从头构建新的 UI 组件;构建时请使用 获取指导。对于纯后端变更、CLI 或没有 UI 输出的库代码,也不要使用此 Skill。
frontend-ui-engineeringWorkflow
工作流
Phase 1: Route New UI Work
阶段 1:路由新的 UI 工作
For component construction, interaction patterns, and focus-management guidance, use . Do not restate that skill here. Return to this workflow once an interface exists and needs auditing or remediation.
../frontend-ui-engineering/SKILL.md有关组件构建、交互模式和焦点管理的指导,请使用 。此处不要重复该 Skill 的内容。当界面已经存在并需要审计或修复时,请返回此工作流。
../frontend-ui-engineering/SKILL.mdPhase 2: Run Automated Audit
阶段 2:运行自动化审计
Execute accessibility checks in this order:
bash
undefined按以下顺序执行无障碍检查:
bash
undefinedaxe-core rules through pinned @axe-core/cli (the axe-core package ships no CLI)
axe-core rules through pinned @axe-core/cli (the axe-core package ships no CLI)
npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --exit
npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --exit
Keep the JSON for the accessibility-auditor
Keep the JSON for the accessibility-auditor
npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --dir ./a11y-reports --save axe.json
npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --dir ./a11y-reports --save axe.json
Pinned pa11y for HTML validation (WCAG2AA rules via HTML_CodeSniffer)
Pinned pa11y for HTML validation (WCAG2AA rules via HTML_CodeSniffer)
npx --yes pa11y@9.1.1 http://localhost:3000
For a combined report, run `bash skills/accessibility-engineering/scripts/audit-a11y.sh url <url> --json`. It runs both pinned tools, records their status and versions, and fails rather than reporting a clean result when either tool does not produce a valid report.
Review the violations grouped by severity:
- **Critical** — Blocks screen reader access entirely (missing alt text on info images, empty buttons)
- **Serious** — Makes content difficult or impossible to access (low contrast, missing labels)
- **Moderate** — Causes confusion or extra effort (heading level skips, redundant ARIA)
- **Minor** — Cosmetic or progressive enhancement (missing lang attribute on inner elements)
For each violation, verify it's a real issue (not a false positive) by inspecting the element in the browser.npx --yes pa11y@9.1.1 http://localhost:3000
若要生成合并报告,请运行 `bash skills/accessibility-engineering/scripts/audit-a11y.sh url <url> --json`。该脚本会运行两个固定版本的工具,记录其状态和版本;如果任一工具未生成有效报告,脚本会失败,而不是报告“检查通过”。
按严重程度分类审查各项违规:
- **Critical(关键)**——完全阻断屏幕阅读器访问(信息图片缺少 alt 文本、空白按钮)
- **Serious(严重)**——使内容难以访问或无法访问(对比度不足、缺少标签)
- **Moderate(中等)**——造成困惑或增加操作负担(标题层级跳级、冗余 ARIA)
- **Minor(轻微)**——仅影响外观或渐进增强效果(内部元素缺少 lang 属性)
对于每项违规,通过在浏览器中检查元素,确认它确实是问题而非误报。Phase 3: Manual Testing
阶段 3:手动测试
Automated checks are a smoke test, not proof of conformance. Complete the audit manually.
Keyboard audit:
- Tab through every interactive element — can you see where you are?
- Activate buttons and links with Enter/Space
- Close modals with Escape
- Navigate lists with Arrow keys
- Verify no keyboard traps exist
Screen reader audit (VoiceOver on macOS, NVDA on Windows):
- Navigate by heading (VoiceOver: Ctrl+Option+Cmd+H) — is the structure logical?
- Navigate by landmark (open the rotor with Ctrl+Option+U, choose Landmarks) — are regions labeled?
- Navigate by link (open the rotor with Ctrl+Option+U, choose Links) — do link descriptions make sense out of context?
- Interact with a form — are labels announced? Are error messages read?
- Navigate a dynamic update — are changes announced?
Visual audit:
- Verify color contrast (4.5:1 text, 3:1 large text, 3:1 UI components)
- Zoom to 200% — does layout break or overlap?
- Test with forced colors / high contrast mode (Windows High Contrast)
- Reduce motion (prefers-reduced-motion) — are animations disabled?
- Test focus visibility — is the focus ring visible against all backgrounds?
自动化检查只是冒烟测试,不能证明符合性。必须手动完成审计。
键盘审计:
- 使用 Tab 键遍历每个交互元素——你能看到当前位置吗?
- 使用 Enter/Space 激活按钮和链接
- 使用 Escape 关闭模态框
- 使用方向键浏览列表
- 确认不存在键盘陷阱
屏幕阅读器审计(macOS 上的 VoiceOver、Windows 上的 NVDA):
- 按标题导航(VoiceOver:Ctrl+Option+Cmd+H)——结构是否符合逻辑?
- 按地标导航(使用 Ctrl+Option+U 打开转子,然后选择 Landmarks)——各区域是否有标签?
- 按链接导航(使用 Ctrl+Option+U 打开转子,然后选择 Links)——脱离上下文后,链接描述是否仍然合理?
- 与表单交互——标签是否会被朗读?错误消息是否会被读取?
- 浏览动态更新——更改是否会被播报?
视觉审计:
- 验证颜色对比度(普通文本 4.5:1、大号文本 3:1、UI 组件 3:1)
- 缩放到 200%——布局是否出现断裂或重叠?
- 使用强制颜色/高对比度模式进行测试(Windows High Contrast)
- 减少动态效果()——动画是否已禁用?
prefers-reduced-motion - 测试焦点可见性——焦点环在所有背景上是否都清晰可见?
Phase 4: Fix Violations
阶段 4:修复违规问题
For each finding, apply the remediation in order:
- Fix the root cause — Replace a with
<div>, add<button>, set<label>textalt - Add ARIA as bridge — If native HTML can't express the pattern, add ARIA attributes
- Test the fix — Re-run the automated check and manual verification
Apply the accessibility checklist () as a minimal baseline.
../../references/accessibility-checklist.md对于每项审计结果,按以下顺序应用修复措施:
- 修复根本原因——将 替换为
<div>,添加<button>,设置 alt 文本<label> - 将 ARIA 作为桥梁——如果原生 HTML 无法表达某种模式,则添加 ARIA 属性
- 测试修复结果——重新运行自动化检查和手动验证
应用无障碍检查清单()作为最低基准。
../../references/accessibility-checklist.mdCommon Rationalizations
常见理由
| Rationalization | Reality |
|---|---|
| "We'll fix a11y later" | Delayed remediation compounds across components and can create legal liability. Audit before shipping. |
| "Automated tools caught everything" | Automated checks cannot prove keyboard or screen reader behavior. Manual testing is mandatory. |
| "Screen reader users are a tiny minority" | Accessibility is a requirement, not a usage-share calculation. Keyboard navigation, captions, and clear structure also help users across contexts. |
| "This is an internal tool, it doesn't need a11y" | Internal tools are subject to the same regulations. Disabled employees and contractors need access. |
| "I'll just use aria-label everywhere" | ARIA is a bridge, not a foundation. Semantic HTML first. Overusing ARIA creates maintenance burden and can make things worse. |
| "The design system handles accessibility" | Design systems provide accessible primitives. How you compose them determines whether the result is accessible. |
| "The audit passed axe-core, so we're done" | Pass axe-core as a smoke test, then test with screen readers and keyboard. A green lighthouse score is not a clean bill of health. |
| 常见理由 | 实际情况 |
|---|---|
| “我们以后再修复 a11y” | 推迟修复会在多个组件中不断累积,并可能造成法律责任。应在发布前进行审计。 |
| “自动化工具已经发现了所有问题” | 自动化检查无法证明键盘或屏幕阅读器的行为正常。必须进行手动测试。 |
| “屏幕阅读器用户占极少数” | 无障碍是一项要求,而不是根据使用占比计算的结果。键盘导航、字幕和清晰结构也能帮助不同场景中的用户。 |
| “这是内部工具,不需要 a11y” | 内部工具同样受到法规约束。残障员工和承包商也需要访问权限。 |
| “我在所有地方都加上 aria-label 就行” | ARIA 是桥梁,而不是基础。应优先使用语义化 HTML。过度使用 ARIA 会增加维护负担,甚至让情况变得更糟。 |
| “设计系统已经处理了无障碍问题” | 设计系统提供无障碍基础组件。你如何组合它们决定了最终结果是否无障碍。 |
| “axe-core 审计通过了,所以完成了” | 将 axe-core 作为冒烟测试,然后使用屏幕阅读器和键盘进行测试。Lighthouse 评分全绿并不代表完全没有问题。 |
Red Flags
风险信号
- Elements that look clickable but aren't keyboard-focusable
- Color as the sole indicator of state (red for error, green for success)
- Focus outline removed without a visible replacement
- Missing labels on form inputs
- No heading hierarchy or skipped heading levels
- Empty or unlabeled buttons and links
- Modals that don't trap focus or restore focus on close
- No text on meaningful images (or
altmissing on decorative ones)alt="" - Touch targets that fail SC 2.5.8's 24x24 CSS px size-or-spacing requirement and do not qualify for an exception (AA; 44x44 is the AAA target, SC 2.5.5)
- Autoplaying video or audio without controls
- Low contrast text (especially on hover, disabled states, placeholders)
- 元素看起来可点击,但无法通过键盘聚焦
- 仅使用颜色表示状态(红色表示错误,绿色表示成功)
- 移除了焦点轮廓,却没有提供可见的替代样式
- 表单输入框缺少标签
- 没有标题层级或存在标题层级跳级
- 按钮和链接为空或没有标签
- 模态框未限制焦点,或关闭后未恢复焦点
- 有意义的图片缺少 文本,或者装饰性图片缺少
altalt="" - 触控目标不符合 SC 2.5.8 的 24x24 CSS px 尺寸或间距要求,且不符合任何例外条件(AA;44x44 是 AAA 目标,SC 2.5.5)
- 视频或音频自动播放且没有控件
- 文本对比度低,尤其是在悬停、禁用状态和占位符中
See Also
另请参阅
- — Quick reference for WCAG 2.2 AA
../../references/accessibility-checklist.md - — Building accessible components from the start
../frontend-ui-engineering/SKILL.md - — Dedicated a11y audit persona for deep reviews
../../agents/accessibility-auditor.md
- ——WCAG 2.2 AA 快速参考
../../references/accessibility-checklist.md - ——从头构建无障碍组件
../frontend-ui-engineering/SKILL.md - ——用于深入审查的专用 a11y 审计角色
../../agents/accessibility-auditor.md
Verification
验证
After completing the accessibility workflow:
- Automated audit passes with no Critical or Serious violations
- All interactive elements are keyboard accessible (Tab, Enter, Escape, Arrow keys)
- Screen reader navigation by heading, landmark, and link verified with a named browser + AT pair (or recorded as and untested — never reported as verified)
manual - Focus order matches visual order
- Color contrast passes 4.5:1 text / 3:1 large text / 3:1 UI components
- All form inputs have associated labels
- All images have appropriate text
alt - Dynamic content changes are announced (aria-live)
- Page is usable at 200% zoom with no content loss
- Touch targets satisfy SC 2.5.8's 24x24 CSS px size-or-spacing requirement or a normative exception (AA); 44x44 is the enhanced AAA target (SC 2.5.5)
完成无障碍工作流后:
- 自动化审计通过,且没有 Critical 或 Serious 违规问题
- 所有交互元素均可通过键盘访问(Tab、Enter、Escape、方向键)
- 已使用明确指定的浏览器与 AT 组合,验证按标题、地标和链接进行屏幕阅读器导航(或记录为 且未经测试——绝不报告为已验证)
manual - 焦点顺序与视觉顺序一致
- 颜色对比度满足普通文本 4.5:1、大号文本 3:1、UI 组件 3:1 的要求
- 所有表单输入框都有关联的标签
- 所有图片都有适当的 文本
alt - 动态内容更改会被播报()
aria-live - 页面在 200% 缩放下仍可使用,且不会丢失内容
- 触控目标满足 SC 2.5.8 的 24x24 CSS px 尺寸或间距要求,或符合规范性例外条件(AA);44x44 是增强的 AAA 目标(SC 2.5.5)