mcpField
A
a11y-debugging

a11y-debugging

github.com/gsmlg-dev测试与质量036 次安装3 周前更新
代码仓库

关于 a11y-debugging

a11y-debugging 是一项用于调试网页无障碍问题的技能，面向使用浏览器工具检查页面的开发者。它结合 Lighthouse 审计、无障碍树、键盘测试和页面脚本检查来定位问题。

主要功能

  1. 01运行 Lighthouse 无障碍审计
  2. 02检查无障碍树与标题层级
  3. 03检查控件名称、表单标签和图片替代文本
  4. 04测试键盘焦点与弹窗焦点管理
  5. 05检查触控目标尺寸和颜色对比度

适用场景

  1. 01排查网页中缺少标签的表单控件
  2. 02核对页面标题结构与阅读顺序
  3. 03检查弹窗打开后的键盘焦点行为

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gsmlg-dev/code-agent --skill a11y-debugging

安装后在 Claude Code 中输入/a11y-debugging确认已加载。

附带文件references/a11y-snippets.md

详细介绍

核心概念

无障碍树与 DOM：以视觉方式隐藏元素（例如，CSS opacity: 0）对屏幕阅读器的影响，与 display: none 或 aria-hidden="true" 不同。take_snapshot 工具返回页面的无障碍树，它呈现了辅助技术“看到”的内容，因此是语义结构最可靠的事实来源。

阅读 web.dev 文档：如果需要查阅特定的无障碍指南（例如 https://web.dev/articles/accessible-tap-targets），可以在 URL 后追加 .md.txt（例如 https://web.dev/articles/accessible-tap-targets.md.txt），以获取干净的原始 Markdown 版本。这样更容易阅读！

工作流模式

1. 自动化审计（Lighthouse）

首先运行 Lighthouse 无障碍审计，获取全面的基线结果。此工具会提供总体评分，并列出具体的不合格元素及修复建议。

  1. 运行审计：
    • 将 mode 设为 "navigation"，以刷新页面并捕获加载问题。
    • 设置 outputDirPath（例如 /tmp/lh-report），以保存完整的 JSON 报告。
  2. 分析摘要：
    • 检查 scores（范围为 0-1）。评分 < 1 表示存在违规。
    • 查看 audits.failed 数量。
  3. 查看报告（重要）：
    • 解析：不要逐行读取整个文件。使用 jq 等命令行工具或一行 Node.js 命令筛选失败项： 
      # 提取失败的审计项及其详情
node -e "const r=require('./report.json'); Object.values(r.audits).filter(a=>a.score!==null && a.score<1).forEach(a=>console.log(JSON.stringify({id:a.id, title:a.title, items:a.details?.items})))"
    • 这样可以高效提取不合格元素的 selector 和 snippet，而无需将完整报告加载到上下文中。
2. 浏览器问题与审计

Chrome 会自动检查常见的无障碍问题。使用 list_console_messages 检查这些原生审计结果：

  • types：["issue"]
  • includePreservedMessages：true（用于捕获页面加载期间发生的问题）

这样通常无需手动调查，就能发现标签缺失、ARIA 属性无效及其他严重错误。

3. 语义与结构

无障碍树会显示标题层级和语义地标。

  1. 导航到页面。
  2. 使用 take_snapshot 捕获无障碍树。
  3. 检查标题级别：确保标题级别（h1、h2、h3 等）符合逻辑，且没有跳级。快照会包含标题角色。
  4. 内容顺序调整：确认 DOM 顺序（决定无障碍树的顺序）与视觉阅读顺序一致。使用 take_screenshot 检查视觉布局，并与快照结构进行对比，以发现导致逻辑顺序混乱的 CSS 浮动或绝对定位。
4. 标签、表单与文本替代内容
  1. 在 take_snapshot 输出中查找按钮、输入框和图片。
  2. 确保交互元素具有无障碍名称（例如，如果按钮只包含图标，其名称不应只是 ""）。
  3. 无关联标签的输入框：确认所有表单输入框都关联了标签。使用 evaluate_script 执行 references/a11y-snippets.md 中的 “查找无关联标签的表单输入框”代码片段。
  4. 检查图片是否具有 alt 文本。
5. 焦点与键盘导航

在没有视觉反馈的情况下测试“键盘陷阱”和正确的焦点管理，需要跟踪当前获得焦点的元素。

  1. 使用 press_key 工具，通过 "Tab" 或 "Shift+Tab" 移动焦点。
  2. 使用 take_snapshot 捕获更新后的无障碍树。
  3. 在快照中查找标记为已聚焦的元素，确认焦点已移至预期的交互元素。
  4. 如果打开了模态框，焦点必须移入其中，并一直“困”在模态框内，直到模态框关闭。
6. 点击目标和视觉效果

根据 web.dev 的建议，点击目标应至少为 48x48 像素，并留有足够的间距。由于无障碍树不会显示尺寸，请使用 evaluate_script，并运行 references/a11y-snippets.md 中的 “Measure Tap Target Size”代码片段。

将快照中的元素 uid 作为参数传递给 evaluate_script。

7. 颜色对比度

要验证颜色对比度，请先检查原生无障碍问题：

  1. 使用 types: ["issue"] 调用 list_console_messages。
  2. 在输出中查找“Low Contrast”问题。

如果原生审计未报告问题（某些无头环境中可能会出现这种情况），或者你需要手动检查特定元素，请使用 evaluate_script，并运行 references/a11y-snippets.md 中的 “Check Color Contrast”代码片段。

8. 全局页面检查

使用 references/a11y-snippets.md 中的 “Global Page Checks”代码片段，验证组件测试中经常遗漏的文档级无障碍设置。

故障排除

如果标准无障碍查询失败，或 evaluate_script 代码片段返回意外结果：

  • 视觉检查：如果自动化脚本无法确定对比度（例如，文字位于渐变图像或复杂背景上），请使用 take_screenshot 截取该元素。虽然模型无法根据图像测量精确的对比度，但可以通过视觉评估可读性并发现明显问题。

评论

支持 Markdown