SuperAPI AI 工具集

accessibility-inspect

测试与质量

查看项目

更新于 10-15 10:29

技能介绍

用途

accessibility-inspect 是 accesslint/skills 提供的半自动手动无障碍(a11y)检查技能,面向 WCAG 评估中规则引擎无法判定的部分。这些检查需要与页面交互(键盘、焦点、状态变化、重排)或人工审查(焦点可见性、错误恢复、阅读顺序)。该技能针对运行中的页面工作,仅在需要将发现映射到 file:line 时参考源代码。它只负责定位与评估,不负责修复——修复由 accesslint:accessibility-fix 承担。自动扫描层为 accesslint:accessibility-scan;accesslint:accessibility-audit 则在 WCAG-EM 下同时运行两者。

主要能力

该技能按检查点区域组织,每个区域对应一组 WCAG 成功准则(SC)和触发条件:

  • 键盘与焦点:2.1.1、2.1.2、2.4.3、2.4.7、2.4.11,始终执行一次批量遍历。
  • 结构与语义:1.3.1、1.3.2、2.4.1、2.4.6,始终从初始快照读取,无需额外驱动。
  • 名称、角色、状态:4.1.2、2.5.3、4.1.3,在存在自定义组件或有状态控件时触发(静态名称存在性由引擎负责)。
  • 视觉适配:1.4.1、1.4.4、1.4.10、1.4.12、1.3.4、2.3.3、1.4.11,每页执行一次重排/缩放;仅在存在动效时检查动效。
  • 表单与错误:3.3.1–3.3.3、1.3.5、3.3.7、3.3.8,在存在表单时触发(标签/自动完成存在性由引擎负责)。
  • 媒体与计时:1.2.x、2.2.1、2.2.2,在存在 video/audio、自动播放或超时时触发。
  • 指针与目标:2.5.1、2.5.7、2.5.8,目标尺寸从批量遍历中免费获得;仅在存在拖拽界面时检查拖拽。
  • 内容与导航:3.1.1/2、2.4.4、3.2.3/4、3.2.6,lang 和链接目的从快照读取;跨页一致性属于 accessibility-audit(此处不执行)。

每个检查点的详细步骤和默认评级见 references/checkpoints.md;当用户要求深度检查(--deep)时,会驱动每个触发区域走完整流程。

使用方式

该技能通过浏览器 MCP 运行:推荐 chrome-devtools,也支持 playwright 或 puppeteer。若未连接任何浏览器 MCP,则只运行静态检查,其余报告为 ○ 人工交接,并提示用户运行:

claude mcp add chrome-devtools npx -- -y chrome-devtools-mcp@latest

目标($ARGUMENTS)可以是 URL、accesslint.config.json 中的目标名,或留空使用默认目标。--selector <css> 可将范围限定到某个组件;--wait-for <css> 等待异步内容。navigate_page 需要 URL,因此先解析:若为 URL 则直接使用;若为目标名或留空,则读取 accesslint.config.json(以及被 gitignore 的 accesslint.config.local.json 覆盖层),将名称(或默认)解析为 url,同时取其 waitFor 和 selector;若无配置,则询问 URL,或建议运行 npx @accesslint/cli init。随后导航到 URL 并等待门控(--wait-for 若给出,否则使用目标的 waitFor)后再测试。

驱动效率方面:等待门控后只取一次完整快照,作为结构、名称、角色、状态和 N/A 决策的基础;状态变化后不要重新快照整个页面,而是通过 evaluate_script 限定到变化组件的选择器读取,或只快照该子树。键盘遍历应批量执行:在一次 evaluate_script 调用中计算可 Tab 序列,按顺序 focus() 每个元素,并返回每个停靠点的紧凑 JSON——选择器、角色/名称、document.activeElement 确认、:focus 上的计算 outline/box-shadow、边界框(免费确定 2.5.8),以及元素是否位于粘性/覆盖矩形下(2.4.11)。该遍历是确定性 DOM 事实,结果可 ● 引用。遍历发现候选,真实按键事件确认行为:脚本化 focus() 不会运行应用的 keydown 处理器,因此可操作性(Enter/Space/方向键)和陷阱断言仍需 press_key,但只在遍历的疑似点执行——复合组件(roving tabindex、aria-activedescendant)、可能捕获 Tab/Esc 的元素、遍历无法到达的元素。● 键盘陷阱发现需要在该组件上真实按下 Tab/Esc,不需要在页面每个组件上都按。

适用场景

适用于需要对运行中的网页进行半自动 WCAG 手动检查的场景,尤其是规则引擎无法判定的交互性和人工判断项。对于拖拽、富文本编辑器、树视图、数据网格、自定义组合框或菜单、轮播以及大量 toast 或 live-region 的界面,启发式检查不可靠:应命名 APG 模式,验证能验证的部分(●/◐),其余作为 ○ 交接,并给出要运行的辅助技术步骤。可使用 explain_rule 查询引擎规则,使用 APG 查询组件契约。

限制

  • 该技能只定位和评估,不修复。
  • 无障碍树显示的是机器状态,不是屏幕阅读器实际播报的内容;aria-live 存在不代表会播报。
  • 浏览器缩放无法直接暴露;CSS 缩放近似为 ◐。
  • 必须在初始快照前等待异步内容;之后优先使用选择器限定读取而非重新快照。
  • 证据分级有严格上限:● 需完整证明(选择器、交互、观察到的 DOM 或无障碍树事实),只收集一次;◐ 硬性上限为一个选择器、一张截图(仅当问题是视觉的)、你的意见以及需要人工确认的内容;○ 零驱动,只命名功能能力、辅助技术和已执行的流程。
  • 未执行(Not exercised)是合法且诚实的结果,报告为未确定,绝不静默丢弃,也绝不作为通过。
  • 去重应在驱动前进行:引擎(accessibility-scan)负责静态可检测的准则——名称/标签存在性、lang、autocomplete、语义标记、平坦背景上的文本对比度。若提供了扫描结果集或引擎负责的 SC 列表,则不再重复检查这些准则,而是将其记为引擎负责。
  • 组合各层(与 accessibility-scan 去重、共享一个浏览器)是 accessibility-audit 的职责。单独运行时,该技能报告其检查发现的内容,其账本说明未检查的内容。