accessibility-engineering

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Accessibility 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
frontend-ui-engineering
for construction guidance. Do not use for backend-only changes, CLIs, or library code with no UI output.
  • 在发布需要接受无障碍审计的面向用户的变更之前
  • 当有人报告 a11y 问题时(例如,“屏幕阅读器无法读取此内容”“键盘导航失效”)
  • 当需要审计现有界面的符合性时
  • 当需要分诊 axe-core 或 pa11y 的审计结果时
  • 当需要修复已确认的无障碍违规问题时
请勿用于从头构建新的 UI 组件;构建时请使用
frontend-ui-engineering
获取指导。对于纯后端变更、CLI 或没有 UI 输出的库代码,也不要使用此 Skill。

Workflow

工作流

Phase 1: Route New UI Work

阶段 1:路由新的 UI 工作

For component construction, interaction patterns, and focus-management guidance, use
../frontend-ui-engineering/SKILL.md
. 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 的内容。当界面已经存在并需要审计或修复时,请返回此工作流。

Phase 2: Run Automated Audit

阶段 2:运行自动化审计

Execute accessibility checks in this order:
bash
undefined
按以下顺序执行无障碍检查:
bash
undefined

axe-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:
  1. Tab through every interactive element — can you see where you are?
  2. Activate buttons and links with Enter/Space
  3. Close modals with Escape
  4. Navigate lists with Arrow keys
  5. Verify no keyboard traps exist
Screen reader audit (VoiceOver on macOS, NVDA on Windows):
  1. Navigate by heading (VoiceOver: Ctrl+Option+Cmd+H) — is the structure logical?
  2. Navigate by landmark (open the rotor with Ctrl+Option+U, choose Landmarks) — are regions labeled?
  3. Navigate by link (open the rotor with Ctrl+Option+U, choose Links) — do link descriptions make sense out of context?
  4. Interact with a form — are labels announced? Are error messages read?
  5. Navigate a dynamic update — are changes announced?
Visual audit:
  1. Verify color contrast (4.5:1 text, 3:1 large text, 3:1 UI components)
  2. Zoom to 200% — does layout break or overlap?
  3. Test with forced colors / high contrast mode (Windows High Contrast)
  4. Reduce motion (prefers-reduced-motion) — are animations disabled?
  5. Test focus visibility — is the focus ring visible against all backgrounds?
自动化检查只是冒烟测试,不能证明符合性。必须手动完成审计。
键盘审计:
  1. 使用 Tab 键遍历每个交互元素——你能看到当前位置吗?
  2. 使用 Enter/Space 激活按钮和链接
  3. 使用 Escape 关闭模态框
  4. 使用方向键浏览列表
  5. 确认不存在键盘陷阱
屏幕阅读器审计(macOS 上的 VoiceOver、Windows 上的 NVDA):
  1. 按标题导航(VoiceOver:Ctrl+Option+Cmd+H)——结构是否符合逻辑?
  2. 按地标导航(使用 Ctrl+Option+U 打开转子,然后选择 Landmarks)——各区域是否有标签?
  3. 按链接导航(使用 Ctrl+Option+U 打开转子,然后选择 Links)——脱离上下文后,链接描述是否仍然合理?
  4. 与表单交互——标签是否会被朗读?错误消息是否会被读取?
  5. 浏览动态更新——更改是否会被播报?
视觉审计:
  1. 验证颜色对比度(普通文本 4.5:1、大号文本 3:1、UI 组件 3:1)
  2. 缩放到 200%——布局是否出现断裂或重叠?
  3. 使用强制颜色/高对比度模式进行测试(Windows High Contrast)
  4. 减少动态效果(
    prefers-reduced-motion
    )——动画是否已禁用?
  5. 测试焦点可见性——焦点环在所有背景上是否都清晰可见?

Phase 4: Fix Violations

阶段 4:修复违规问题

For each finding, apply the remediation in order:
  1. Fix the root cause — Replace a
    <div>
    with
    <button>
    , add
    <label>
    , set
    alt
    text
  2. Add ARIA as bridge — If native HTML can't express the pattern, add ARIA attributes
  3. Test the fix — Re-run the automated check and manual verification
Apply the accessibility checklist (
../../references/accessibility-checklist.md
) as a minimal baseline.
对于每项审计结果,按以下顺序应用修复措施:
  1. 修复根本原因——将
    <div>
    替换为
    <button>
    ,添加
    <label>
    ,设置 alt 文本
  2. 将 ARIA 作为桥梁——如果原生 HTML 无法表达某种模式,则添加 ARIA 属性
  3. 测试修复结果——重新运行自动化检查和手动验证
应用无障碍检查清单(
../../references/accessibility-checklist.md
)作为最低基准。

Common Rationalizations

常见理由

RationalizationReality
"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
    alt
    text on meaningful images (or
    alt=""
    missing on decorative ones)
  • 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)
  • 元素看起来可点击,但无法通过键盘聚焦
  • 仅使用颜色表示状态(红色表示错误,绿色表示成功)
  • 移除了焦点轮廓,却没有提供可见的替代样式
  • 表单输入框缺少标签
  • 没有标题层级或存在标题层级跳级
  • 按钮和链接为空或没有标签
  • 模态框未限制焦点,或关闭后未恢复焦点
  • 有意义的图片缺少
    alt
    文本,或者装饰性图片缺少
    alt=""
  • 触控目标不符合 SC 2.5.8 的 24x24 CSS px 尺寸或间距要求,且不符合任何例外条件(AA;44x44 是 AAA 目标,SC 2.5.5)
  • 视频或音频自动播放且没有控件
  • 文本对比度低,尤其是在悬停、禁用状态和占位符中

See Also

另请参阅

  • ../../references/accessibility-checklist.md
    — Quick reference for WCAG 2.2 AA
  • ../frontend-ui-engineering/SKILL.md
    — Building accessible components from the start
  • ../../agents/accessibility-auditor.md
    — Dedicated a11y audit persona for deep reviews
  • ../../references/accessibility-checklist.md
    ——WCAG 2.2 AA 快速参考
  • ../frontend-ui-engineering/SKILL.md
    ——从头构建无障碍组件
  • ../../agents/accessibility-auditor.md
    ——用于深入审查的专用 a11y 审计角色

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
    manual
    and untested — never reported as verified)
  • 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
    alt
    text
  • 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)