auditing-wcag

日本語版 (Japanese)

WCAG 一致性审计

你将执行 WCAG 2.2 AA 一致性审计。按成功标准报告 Pass/Fail/NT/NA，并提供证据。

何时使用此技能

视角	reviewing-a11y	auditing-wcag
目标	发现问题并提出修复建议	系统性验证一致性
输出	按严重程度分类的问题列表	按成功标准报告 Pass/Fail/NT/NA
范围	聚焦实际问题	完整覆盖 WCAG 2.2 A/AA

路由规则

• auditing-wcag：用户要求进行“审计”“合规性”“一致性”或正式报告时使用。
• reviewing-a11y：用户要求“审查”“发现问题”“改进”或开发反馈时使用。
• 如果目标不明确，请询问用户希望得到合规报告还是问题审查。

工作流（6 步）

1. 接收输入

• 接受 URL 或本地文件路径。
• 对于多个页面，请确认页面列表和入口。
• 对于本地文件，使用可用的文件读取能力（无法执行运行时行为）。

2. 确定范围

确认并取得用户同意：

• 目标级别（A/AA，默认为 WCAG 2.2 AA）
• 页面范围（所有页面／代表性页面／提供的 URL）
• 限制（不包括 AT 检查；动态行为取决于 Playwright）
• 输出格式（按成功标准报告 Pass/Fail/NT/NA）

3. 自动化检查

• 使用 Playwright 导航并捕获无障碍树。
• 应用 references/automated-checks.md。
• 如果无法进行浏览器交互，通过 a11y-audit CLI 运行检查（参见下文“自动化检查 CLI”）。
• 如果 CLI 也无法运行，则使用可用的网页功能获取 HTML，并据此限制判断范围。
• 使用 references/coverage-matrix.md 确保覆盖 A/AA。

使用知识库整理结果（a11y-knowledge）：

• 还要运行 @a11y-skills/audit 0.14.0 或更高版本中的 page-snapshot（即使缩小 --checks 范围也要包含它）。它不提供判定结果，但可作为 2.4.1／2.4.2／3.1.1 的判定依据，以及比较多个页面的材料。
• 根据 checks-axe.md 和 checks-audit.md 中的规则，将结果整理为“已确定／需要审查”。只有其中列出的 axe 规则，其通过结果才能计为符合（Pass）。其他任何规则通过，都只能说明“该规则检查范围内未发现问题”。
• 对于需要审查的标准，在作出判断前，先阅读 ../a11y-knowledge/references/criteria/<number>.md 中的“判定依据”和“检查时”。“不得断言”部分中的内容应保持为 NT，并注明需要哪些信息才能确定。
• 审计多个页面时，先阅读 cross-page.md 中的共享判定规则。
• 如果某个项目与 references/automated-checks.md 中的内容重叠，以知识库规则为准。知识库通过相对路径 ../a11y-knowledge/ 引用（作为插件安装时，该路径会解析；如果通过符号链接单独安装技能目录，也要链接 a11y-knowledge）。

4. 交互式检查

• 使用 Playwright 验证键盘访问和焦点行为。
• 按照 references/interactive-checks.md 执行。
• 如果无法执行，将受影响的标准标记为 NT。

5. 手动检查项目

• 展示 references/manual-checks.md 和 references/content-checks.md 中的项目。
• 如果没有可用证据，将这些项目保留为 NT，并明确列出。
• 纳入用户提供的任何证据。

6. 生成报告

• 按照 references/output-format.md 执行。
• 为每项 A/AA 成功标准指定状态（Pass/Fail/NT/NA）。
• 总结范围、限制、工具和未解决的项目。

自动化范围与限制

• Playwright 仅提供计算后的无障碍树信号（角色／名称／状态）。
• 自动化测试结果本身不能保证审核结果。
• 屏幕阅读器验证和辅助技术与浏览器的兼容性测试不在范围内。
• 不要猜测；缺少证据时使用 NT。

参考指南

• references/automated-checks.md
• references/interactive-checks.md
• references/manual-checks.md
• references/content-checks.md
• references/output-format.md
• references/coverage-matrix.md
• 知识库（../a11y-knowledge/）：references/checks-axe.md、references/checks-audit.md、references/cross-page.md、references/criteria/<number>.md

自动化检查 CLI

自动化检查通过 npm 包 @a11y-skills/audit 中包含的 a11y-audit CLI 运行（需要 Node 18+；npm 7+ 会自动获取对等依赖）。

首次设置：

npx playwright install chromium

运行所有检查：

npx -y @a11y-skills/audit --url "https://example.com"

运行指定检查：

npx -y @a11y-skills/audit --url "https://example.com" --checks axe-audit,focus-indicator-check,page-snapshot

即使缩小 --checks 的范围，也要包含 page-snapshot（0.14.0 或更高版本）。它是 2.4.1 / 2.4.2 / 3.1.1 的材料，也可用于比较多个页面。

生成带注释的屏幕截图（focus-indicator）：

npx -y @a11y-skills/audit --url "https://example.com" --checks focus-indicator-check --screenshot

自定义输出目录（默认为 ./a11y-audit-results）：

npx -y @a11y-skills/audit --url "https://example.com" --output-dir ./results

退出代码： 0 = 无违规 / 1 = 发现违规 / 2 = 运行时错误

检查名称	标准	描述
axe-audit	多项	axe-core 综合检查
reflow-check	1.4.10	在 320px 宽度下检查水平滚动
text-spacing-check	1.4.12	检查文本间距覆盖导致的裁切
zoom-200-check	1.4.4	检查 200% 缩放时的内容丢失
orientation-check	1.3.4	检测方向锁定
autocomplete-audit	1.3.5	检查缺失或无效的自动完成设置
time-limit-detector	2.2.1	检测计时器或 meta 刷新
auto-play-detection	1.4.2, 2.2.2	检测自动播放内容（视觉变化以及 <audio> / <video> 的播放状态；是否实际听到声音需要人工检查）
focus-indicator-check	2.4.7	检查焦点指示器的可见性
target-size-check	2.5.5, 2.5.8	测量目标尺寸
keyboard-trap-check	2.1.2	检测键盘陷阱
keyboard-reachability-check	2.1.1	检查键盘可达性（Tab、箭头键、activedescendant）
redundant-entry-check	3.3.7	检查是否有重复字段要求填写相同信息（候选项；需要审核）
motion-actuation-check	2.5.4	检查响应设备动作或方向变化的监听器（候选项；需要审核）
change-on-input-check	3.2.2	检查仅更改表单控件就导致的导航、新窗口、焦点移动或对话框（候选项；需要审核）
accessible-authentication-check	3.3.8	检查密码 / 代码字段是否阻止粘贴或设置 autocomplete="off"，以及类似 CAPTCHA 的元素（候选项；需要审核）
pointer-gesture-check	2.5.1, 2.5.7	检查可能需要通过拖动、滑动或多指操作的组件（候选项；需要审核）
focus-order-check	2.4.3	检查 Tab 顺序与视觉顺序是否一致（向上返回、沿行反向移动、绕行），以及打开 / 关闭模态对话框时的焦点（候选项；需要审核）
pointer-cancellation-check	2.5.2	检查仅在按下事件时就执行操作的组件（导航、新窗口、对话框、DOM 变更）以及只有按下监听器的元素（候选项；需要审核）
non-text-contrast-check	1.4.11	检查输入框、复选框、单选按钮和开关的边框或填充色与周围颜色的对比度，以及仅图标按钮中图标的对比度（低于 3:1 或无法测量；需要审核）
character-key-shortcut-check	2.1.4	检查在页面正文聚焦时逐个按下按键，会导致导航、新窗口、对话框、焦点移动、DOM 变更、滚动或 preventDefault() 的按键（候选项；需要审核）
content-on-hover-check	1.4.13	检查悬停或聚焦时显示的内容（根据 CSS :hover / :focus 规则和监听器发现）是否无法通过 Escape 关闭、在指针移到内容上时消失，或自行消失（候选项；需要审核）。仅报告委托的监听器
page-snapshot	2.4.1 / 2.4.2 / 3.1.1 / 3.2.3 / 3.2.4 / 3.2.6 的材料	不作判定。写入 body 的 aria 快照、标题、<html> 的 lang、URL，以及每个 iframe 的 aria 快照（请阅读后判断；对于多个页面，请为每个页面使用单独的 --output-dir 并进行比较）

详细文档请参阅 @a11y-skills/audit README。