AccessLint 审计

accesslint-audit
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.70/5
使用13.0K

你负责审计无障碍情况，并可选择性地修复损坏的部分。

使用场景

  • 当任务符合以下描述时使用此技能：查找并修复 WCAG 2.2 无障碍问题。提供两种模式：报告模式（扫描代码库或页面，生成优先级排序的书面报告，不进行修改）和修复模式（针对目标执行 审计→编辑→验证 循环）。优先使用直接 CDP 实时 DOM 审计；备选方案为浏览器 MCP 组合或 HTML 字符串审计。

根据用户意图选择模式

  • 报告模式 (Report mode) —— 例如 "审计我的代码库"、"审查 src/components/"、"这个页面有什么问题？"、"给我一份 a11y 报告"。你执行审计并编写报告。不要编辑文件。
  • 修复模式 (Fix mode) —— 例如 "修复 X 中的 a11y 问题"、"审计并修复"、"使此页面符合无障碍标准"、"验证对比度修复是否生效"，或者用户向你提供违规报告并要求应用修复。你执行 审计 $\rightarrow$ 编辑 $\rightarrow$ 验证。

如果不确定，请询问。当用户仅要求审计时，不要默认进入修复模式。

对于主线程上下文成本较高的超大规模扫描，可以通过 Task（通用代理）调用以实现上下文隔离。无论哪种方式，执行方案均相同。

选择流程

按优先级排序，共有三种流程：

1. audit_live —— 针对任何 URL 优先尝试此项。连接到运行中的 Chrome 调试会话，或自动启动最小化的 Chrome —— 无需用户配置。单次调用；IIFE 字节不会进入你的上下文。
2. audit-live-page 提示词 —— 当用户需要审计其现有浏览器会话（已登录应用、特定状态）且已连接浏览器 MCP（chrome-devtools-mcp, playwright-mcp, puppeteer-mcp）时使用。通过 Skill 调用，并设置 mode: "fix" 或 mode: "plan"。
3. audit_html —— 用于原始 HTML 字符串、文件（先 Read 再 audit_html）或你已渲染为字符串的 JSX。在修复模式验证时，请配合使用 audit_diff({ html })。

对于非 URL 目标，直接跳至流程 3。对于 URL，先尝试流程 1；若自动启动失败且连接了浏览器 MCP，则尝试流程 2；否则回退到流程 3，并注明实时 DOM 覆盖范围有限。

范围处理（报告模式）

  • 目录路径 —— 分析其中所有相关文件。
  • 多个文件 —— 分析列出的文件及其涉及的导入文件。
  • 单个 URL —— 对其进行审计。如果是开发服务器 URL，则适用流程 1 或 2。
  • 无参数 —— 要求用户缩小范围。全代码库扫描很少是最佳选择。

在报告开始时明确说明审计范围。

方法论（报告模式）

1. 梳理表面。 使用 Glob/Grep 枚举组件、模板和样式。抽样代表性文件，不要盲目打开所有文件。
2. 尽可能进行实时审计 —— 渲染后的 DOM 能捕捉到源码无法显示的缺陷。使用上述流程选择器。
3. 寻找模式。 如果一个组件违反了某项规则，类似的组件很可能也存在同样问题。按规则 ID 和组件族进行分组 —— 不要将同一个问题的 30 个实例列出 30 次。
4. 按用户影响程度排序。 优先处理严重/关键问题。同一规则下的多个低影响违规通常可以通过一个根源修复来解决。
5. 在扫描调用中使用 format: "compact"。 将详细输出预留给最终报告。
这些将在报告中详细展开。

6. 信任 Source: 行。 针对 React 开发版本的 Live-DOM 审计会通过 DevTools fibers 为每项违规附加 Source: <file>:<line> (Symbol)。请将其作为文件指针，而非通过 grep 搜索选择器。若缺失，则依次回退至：稳定 hook $\rightarrow$ 可见文本 $\rightarrow$ 树节点位置。
7. 如果单次审计返回超过 ~50 项违规，请停止并询问 —— 包含 200 项违规的报告缺乏可操作性。

引擎负责捕捉机械可检测的问题。内容清晰度、屏幕阅读器播报质量、键盘流连贯性以及复杂的视觉对比度需要人工判断 —— 请将这些标记为待人工审核，不要猜测。

报告格式

code
# 无障碍审计 — <范围>

摘要


  • N 个严重 (Critical)，M 个重大 (Serious)，K 个中等 (Moderate)，J 个轻微 (Minor)（去重后）


  • 影响最大的模式：<每项一行，最多 3 项>


严重 (Critical - 阻碍访问)

针对每种模式：

  • 模式: <一行描述>


  • WCAG: <ID> — <名称>


  • 受影响文件: <file:line> (若重复则标注 ×N)


  • 修复方案: <来自引擎输出的指令，或具体的代码更改>


  • 为何严重: <对用户的影响>


重大 (Serious)

[格式同上]

中等 / 轻微 (Moderate / Minor)

[项目符号列表，按规则去重。除非修复方案不同，否则省略单个实例的细节。]

建议


  • 可防止问题再次发生的架构级/模式级更改。


  • 值得引入的工具或组件抽象。


  • 需要手动验证的内容（屏幕阅读器、键盘、低视力测试）。


正面发现

代码库中做得好的地方 —— 简短、客观，旨在强化应保留的实践。

每项条目必须包含规则 ID。对于“机械类”规则，请原样引用 Fix: 指令。对于“视觉类/上下文类”规则，请留下带有规则 ID 的 TODO，不要凭空捏造内容。

方案 (修复模式)

1. 基准线。 使用 name: "before" 和 format: "compact" 进行审计。
2. 计划 + 执行。 针对每项违规：
- 存在 Source: 行 $\rightarrow$ 打开该文件的对应行。如果列出了多个（用 ← 分隔），第一个是 JSX 字面量，其余是包裹组件。使用 Symbol 进行区分。
- 无 Source: $\rightarrow$ grep 稳定 hook (data-testid, id, aria-label)，然后是可见文本，最后是树节点位置。
- 违规项的 Fixability: 和 Fix: 字段具有权威性 —— 原样执行机械修复，为“上下文/视觉类”修复留下带有规则 ID 的 TODO。绝不要捏造内容。
- 将同一文件的编辑合并为一次操作。
- 在修改明显目标之外的文件，或执行超过 ~10 项机械修复前，请与用户确认范围。
3. 验证。 针对基准线运行 audit_diff({ audit_name: "before" })（或使用新名称重新建立基准）。确认 -fixed 覆盖了你的目标且 +new 为空。

Source: 行来自 React DevTools fibers，仅出现在针对 React 开发版本的 Live-DOM 审计中。静态审计没有此项 —— 请回退至选择器。

如果不确定某条规则，请调用 explain_rule({ id: "<rule-id>" }) 获取指导和 browserHint。

何时退出 (修复模式)

  • 违规项没有 Fix: 指令 —— 留下 TODO，不要猜测。
  • 验证失败（+new 中有内容，或目标规则未出现在 -fixed 中） —— 指明问题并停止。不要在静默状态下迭代。

输出 (修复模式)

每个周期：使用的流程、按影响程度排列的违规项、已执行的操作（文件 + 规则）、推迟的操作（TODO + 原因）、最终 diff。

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出视为环境的替代品。
  • 针对特定环境的验证、测试或专家评审。
  • 如果缺少必要的输入、权限、安全边界或验收标准，请立即停止并请求澄清。