如何使用 AI 对页面进行无障碍检测

AI
1

WCAG A11y Audit Skill

wcag-a11y-audit 是一个用于网页、组件、弹窗、表单、商品评价/问答区域等场景的无障碍审计 Skill。它面向 WCAG A/AA 审计，强调键盘优先、完整交互覆盖、表单正负例、弹窗内部全量测试、媒体/轮播测试、三态副作用授权、以及简体中文 DOCX 专业报告输出。

注意：本 Skill 用于结构化无障碍审计和整改建议，不等同于法律认证、VPAT 或正式合规声明。

当前支持的审计标准

目前只支持以下两种审计标准：

  1. WCAG 2.2 A/AA

    • 默认标准。
    • 如果使用者没有指定审计标准，默认按 WCAG 2.2 A/AA 审计。
    • 按 WCAG 2.2 报告时，不把 4.1.1 Parsing 作为失败项；duplicate id、broken ARIA refs 等会映射到 4.1.2、1.3.1 或代码质量风险。

  2. WCAG 2.1 A/AA + ETSI EN 301 549 V3.2.1

    • 用于需要 WCAG 2.1 和 EN 301 549 web 对齐审计的场景。
    • 按 WCAG 2.1 / EN 301 549 报告时，保留 4.1.1 Parsing。

不支持的写法示例：

  • WCAG AAA
  • WCAG 2.0
  • 仅 EN 301 549 全量法律认证
  • VPAT 正式认证

安装

使用 sl-skills 安装

sl-skills add https://github.com/TouchFish-Good/wcag-a11y-audit-skill.git --skill wcag-a11y-audit --global

安装后重启或 Reload Codex，让 Skill 生效。

更新

sl-skills update --skill wcag-a11y-audit --yes

手动安装

如果无法使用 sl-skills，也可以手动安装：

git clone https://github.com/TouchFish-Good/wcag-a11y-audit-skill.git
mkdir -p ~/.codex/skills
cp -R wcag-a11y-audit-skill/wcag-a11y-audit ~/.codex/skills/wcag-a11y-audit

更新时：

cd wcag-a11y-audit-skill
git pull
rm -rf ~/.codex/skills/wcag-a11y-audit
cp -R wcag-a11y-audit ~/.codex/skills/wcag-a11y-audit

商家最简使用方式

商家只需要填写 4 行：

URL：
审计标准：WCAG 2.2 A/AA
审计区域：所有关于商品评价的区域
登录态：未登录

示例：

URL：https://example.com/products/demo-product
审计标准：WCAG 2.2 A/AA
审计区域：所有关于商品评价的区域
登录态：未登录

如果不确定审计标准，可以写：

审计标准：默认

此时 Skill 默认使用 WCAG 2.2 A/AA。

完整使用词

复制下面这段给 AI，只需要改最上面的 4 行。

使用 $wcag-a11y-audit 做完整无障碍审计。

URL：
审计标准：WCAG 2.2 A/AA（未指定则默认 WCAG 2.2 A/AA）
审计区域：所有关于商品评价的区域
登录态：未登录

执行契约：
本次审计必须分阶段执行，禁止跳阶段。未完整读取 SKILL.md、未加载必要 references、未在交互前生成 audit-manifest.json、未锁定 locked execution queue、未完成 self-check、未输出通过结构校验的简体中文 DOCX 报告，都视为未完成。

最终回复只能是：
1. report.docx 路径 + audit-manifest.json 路径 + docx-structure-validation.json 路径 + 简短结论；
2. DOCX_BLOCKED 开头的阻塞说明，并附下一步选项：A 不授权并生成报告 / B 授权并提供字段 / C 暂停。
禁止第三种形式。

阶段门禁：
1. 完整读取 SKILL.md 到 EOF，加载必要 references，输出 Preflight Gate。
2. 生成 audit-manifest.json 和 locked execution queue，输出队列摘要，然后等待我确认“开始测试”。
3. 收到“开始测试”后才允许页面交互。
4. 执行 final self-check；任一 NO 必须返工补测到 YES，只有明确阻塞才允许 Incomplete Audit。
5. 生成简体中文 DOCX 报告，并运行 DOCX 结构校验。

Preflight Gate 必须包含：
- SKILL_EOF_CONFIRMED=true
- DOCX_REQUIRED=yes
- REPORT_TEMPLATE_LOADED=yes
- MANIFEST_LOCKED=yes
- QUEUE_LOCKED_BEFORE_INTERACTION=yes
- FORM_MATRIX_LOADED=yes/no/not-applicable
- DOCX_BUILD_ENTRYPOINT_READY=yes
- DOCX_STRUCTURE_VALID=yes

范围规则：
只审计指定区域，但指定区域触发的弹窗、抽屉、popover、媒体预览、分页、加载更多、筛选、表单、回复、点赞、投票、动态状态、错误态、成功态都属于 child scope，必须完整审计。

manifest / queue 规则：
测试前必须锁定所有按钮、链接、图标按钮、非语义可点击元素、表单、字段、正负例、下拉/单选/多选/复选/tabs/筛选/排序、每个选项、弹窗入口和内部控件、图片/媒体/轮播、分页/加载更多、toast/status/loading/error/success、所有可揭示实例直到终态。
禁止边测边补。若发现漏进队列，必须停止，标记 MANIFEST_MISSING_OR_LATE，重建 manifest，从头开始。

完整性规则：
完整审计禁止抽样。页面显示或终态加载出 N 个实例，就必须测 N 个实例。每条评论/问答/卡片/媒体/弹窗/选项/分页/加载更多都要逐项结案。不能完成必须暂停说明阻塞，不能直接跳过。

副作用三态授权规则：
任何会改变页面或服务端状态的动作，如提交、发布、回复、点赞/取消点赞、投票、订阅、上传、删除、举报、下单、支付、账户修改等，必须进入三态授权模型：

- pending-authorization：暂停提问，不能收尾，不能标 unsafe；
- refused-authorization：我拒绝、无法提供必需值，或选择 no-side-effect mode 后，才可标 unsafe-without-authorization，并继续生成 Incomplete DOCX；
- not-required：仅适用于不持久化的动作，如打开、关闭、取消、焦点恢复、确认不会保存数据的负例校验。

遇到副作用时必须使用固定授权模板问我：

需要授权才能继续执行副作用动作：
1. 即将执行的动作：
2. 会改变的页面/服务端状态：
3. 需要你提供的字段：邮箱 / 姓名或昵称 / 文案 / 其他字段值
请选择：A 授权并提供字段；B 不授权并继续生成 Incomplete DOCX；C 暂停审计。

未经明确同意不得执行 final commit。不得编造、复用、拼接、污染、翻译、改写值。
每个副作用必须写入“副作用授权账本”，记录状态、动作、控件、授权问题、我的决定、授权值、是否执行、结果和数据变化 X→Y。

no-side-effect mode：
如果我选择无副作用审计模式，所有 final commit 默认不执行，标 refused/unsafe，但仍必须测试负例、提交前键盘路径、取消/关闭、焦点恢复、状态/错误暴露，并生成 Incomplete DOCX。

负例防污染规则：
每次负例提交前必须读取并记录字段实际值。如果无法确认字段为空或无效，不允许提交。若表单可能 autosave、沿用旧值、恢复草稿或无效值也可能成功提交，负例也按副作用风险处理，必须先授权。

键盘规则：
必须键盘优先：Tab、Shift+Tab、Enter、Space、Escape、方向键、Home/End、PageUp/PageDown、typeahead。鼠标只能 fallback；使用鼠标必须记录键盘为何失败及 WCAG 影响。

弹窗规则：
禁止把 open/close 当完整测试。每个弹窗/抽屉/popover/menu/tooltip/媒体预览必须测试 open、name/description、initial focus、Tab/Shift+Tab、visible focus、所有内部按钮/链接/回复/点赞/表单/选项/图片/视频/轮播控件、Escape、close/cancel、背景 inert、焦点返回、状态/错误/成功消息。漏项必须返工。

表单规则：
所有表单必须测空提交、必填缺失、格式错误、长度/非法字符/边界值、必选项未选、部分填写、错误修正、有效提交前授权、loading、成功/错误提示、旧 toast 残留、aria-invalid、aria-describedby/errormessage、required、AX/读屏暴露、焦点恢复、语言一致性。

选项规则：
所有 select/combobox/listbox/radio/checkbox/multi-select/tabs/chips/筛选项必须生成 Option Ledger。每个选项都测 Tab、Shift+Tab、方向键、Home/End、Enter、Space、选中状态、结果更新、AX/读屏、可见焦点。

媒体规则：
所有图片、图标、媒体、轮播必须生成 Icon / Media / Carousel Ledger，测试 alt/name、装饰性隐藏、功能性名称、预览、上一张/下一张、dots、缩略图、当前状态、Escape、关闭、焦点返回、非文本对比度/焦点/目标大小。

增强检查：
需要检查 AX/读屏状态消息、200% 缩放、Reflow、小视口、文本间距 CSS 注入、行高/字距/词距/段距、hidden/clipped/overlap、像素级对比度、非文本对比度、焦点对比度。报告必须写出 CSS/JS 注入代码、原因和结果。
WAVE / Accessibility Insights 可用则运行；不可用只写 Methodology Notes，不得替代实际键盘/DOM/AX/表单/弹窗测试。

DOCX 结构强校验：
最终 DOCX 必须是真实 Word 文档结构，不能是截图/图片拼成的 DOCX。必须运行 scripts/validate_a11y_docx_structure.mjs，并通过：
- 有真实可选择文本；
- 有真实 Word 表格 w:tbl；
- 包含固定报告标题；
- 不是 image-only / screenshot-based DOCX。
如果失败，必须标 DOCX_FORMAT_INVALID 并重建，不能交付。

最终 self-check：
必须确认是否读到 EOF、是否交互前锁 manifest/queue、是否测完所有实例/选项/表单正负例/弹窗/弹窗内部控件/媒体轮播、是否逐项请求副作用授权、是否只用用户批准值、是否产出所有 ledger、是否生成通过结构校验的简体中文 DOCX。
任一 NO 必须返工补测到 YES；只有明确阻塞才允许 Incomplete Audit。

最终 DOCX 必须包含：
Preflight Gate、Manifest Integrity Gate、审计契约、副作用授权账本、执行摘要、Journey Matrix、Coverage Table、Keyboard Trace、Form Matrix、Option Ledger、Dialog/Media/Carousel Ledger、Icon/Media Control Table、Findings/ISS、Priority Matrix、WCAG Ledger 计数、CSS/JS 注入记录、WAVE/Accessibility Insights 或 Methodology Notes、Limitations、Evidence Index、Final self-check gate。

现在只允许执行阶段 1 和阶段 2。阶段 2 完成后必须等待我回复“开始测试”。

输出物要求

一次完整审计应至少产出：

  • report.docx：简体中文 Word 报告，必须是真实 Word 文本和真实 Word 表格，不能是截图型 DOCX。
  • audit-manifest.json：测试前锁定的执行队列和覆盖账本。
  • docx-structure-validation.json：DOCX 结构校验结果。
  • evidence.json：自动采证、DOM、AX、截图、工具阻塞等原始证据。
  • wcag-ledger.json：WCAG 条目结果台账。

如果无法生成合格 DOCX，最终回复必须以 DOCX_BLOCKED 开头，并说明具体原因。

目录结构

wcag-a11y-audit-skill/
  README.md
  wcag-a11y-audit/
    SKILL.md
    agents/
    references/
    scripts/

适用场景

  • 商品评价区域
  • 商品问答区域
  • 评论/回复/点赞/筛选/排序/加载更多
  • 表单校验
  • 弹窗/抽屉/媒体预览
  • 图片/图标/轮播
  • 键盘导航
  • AX / 读屏状态消息
  • WCAG A/AA 问题定位和修复建议

不适用场景

  • 法律认证
  • VPAT 正式出具
  • WCAG AAA 审计
  • 只依赖自动工具分数替代人工/键盘/AX 审计
  • 未授权的真实支付、下单、删除、举报、隐私数据提交等高风险动作