跳到主内容
智客 ZICQ

技能库 智客分类:Agent 工作流 a11y-debugging

A11y Debugging

使用 Chrome DevTools MCP 进行访问(a11y)调试和基于web.dev准则的审计. 测试语义HTML时使用,ARIA标签,焦点状态,键盘导航,水龙头目标,和颜色对比.

2605 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

使用 Chrome DevTools MCP 进行访问(a11y)调试和基于网络的审计. 详细准则

何时用

测试语义 HTML, ARIA 标签, 焦点状态, 键盘导航, 水龙头目标, 以及颜色对比

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Core Concepts、Workflow Patterns、1. Automated Audit (Lighthouse)、2. Browser Issues & Audits、3. Semantics & Structure、4. Labels, Forms & Text Alternatives。 其中含规范建议的小节:分步指令。

文件分析

文件分析:除 SKILL.md 外,正文引用了 references/a11y-snippets.md,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.

Core ConceptsWorkflow Patterns1. Automated Audit (Lighthouse)2. Browser Issues & Audits3. Semantics & Structure4. Labels, Forms & Text Alternatives5. Focus & Keyboard Navigation6. Tap Targets and Visuals7. Color Contrast8. Global Page ChecksTroubleshooting

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
a11y-debugging
description
Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 1
  • references/a11y-snippets.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「a11y-debugging」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-011141ef0afbcb5e-A11y-%E8%B0%83%E8%AF%95.html
请存为 .cursor/skills/a11y-debugging/SKILL.md 或 .claude/skills/a11y-debugging/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/chromedevtools/chrome-devtools-mcp 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/chromedevtools/chrome-devtools-mcp' --list

npx skills add 'https://github.com/chromedevtools/chrome-devtools-mcp' --skill 'a11y-debugging'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版

name: a11y-debugging description: Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.

Core Concepts

Page Targeting: Page-scoped tools (take_snapshot, list_console_messages, evaluate_script, press_key, take_screenshot, lighthouse_audit, etc.) require a pageId parameter. Retrieve available page IDs using list_pages or from new_page.

Accessibility Tree vs DOM: Visually hiding an element (e.g., CSS opacity: 0) behaves differently for screen readers than display: none or aria-hidden="true". The take_snapshot tool returns the accessibility tree of the page, which represents what assistive technologies "see", making it the most reliable source of truth for semantic structure.

Reading web.dev documentation: If you need to research specific accessibility guidelines (like https://web.dev/articles/accessible-tap-targets), you can append .md.txt to the URL (e.g., https://web.dev/articles/accessible-tap-targets.md.txt) to fetch the clean, raw markdown version. This is much easier to read!

Workflow Patterns

1. Automated Audit (Lighthouse)

Start by running a Lighthouse accessibility audit to get a comprehensive baseline. This tool provides a high-level score and lists specific failing elements with remediation advice.

  1. Run the audit:
    • Set mode to "navigation" to refresh the page and capture load issues.
    • Set outputDirPath (e.g., /tmp/lh-report) to save the full JSON report.
  2. Analyze the Summary:
    • Check scores (0-1 scale). A score < 1 indicates violations.
    • Review audits.failed count.
  3. Review the Report (CRITICAL):
    • Parsing: Do not read the entire file line-by-line. Use a CLI tool like jq or a Node.js one-liner to filter for failures:
      # Extract failing audits with their details
      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})))"
      
    • This efficiently extracts the selector and snippet of failing elements without loading the full report into context.

2. Browser Issues & Audits

Chrome automatically checks for common accessibility problems. Use list_console_messages to check for these native audits:

  • types: ["issue"]
  • includePreservedMessages: true (to catch issues that occurred during page load)

This often reveals missing labels, invalid ARIA attributes, and other critical errors without manual investigation.

3. Semantics & Structure

The accessibility tree exposes the heading hierarchy and semantic landmarks.

  1. Navigate to the page.
  2. Use take_snapshot to capture the accessibility tree.
  3. Check Heading Levels: Ensure heading levels (h1, h2, h3, etc.) are logical and do not skip levels. The snapshot will include heading roles.
  4. Content Reordering: Verify that the DOM order (which drives the accessibility tree) matches the visual reading order. Use take_screenshot to inspect the visual layout and compare it against the snapshot structure to catch CSS floats or absolute positioning that jumbles the logical flow.

4. Labels, Forms & Text Alternatives

  1. Locate buttons, inputs, and images in the take_snapshot output.
  2. Ensure interactive elements have an accessible name (e.g., a button should not just say "" if it only contains an icon).
  3. Orphaned Inputs: Verify that all form inputs have associated labels. Use evaluate_script with the "Find Orphaned Form Inputs" snippet found in references/a11y-snippets.md.
  4. Check images for alt text.

5. Focus & Keyboard Navigation

Testing "keyboard traps" and proper focus management without visual feedback relies on tracking the focused element.

  1. Use the press_key tool with "Tab" or "Shift+Tab" to move focus.
  2. Use take_snapshot to capture the updated accessibility tree.
  3. Locate the element marked as focused in the snapshot to verify focus moved to the expected interactive element.
  4. If a modal opens, focus must move into the modal and "trap" within it until closed.

6. Tap Targets and Visuals

According to web.dev, tap targets should be at least 48x48 pixels with sufficient spacing. Since the accessibility tree doesn't show sizes, use evaluate_script with the "Measure Tap Target Size" snippet found in references/a11y-snippets.md.

Pass the element's uid from the snapshot as an argument to evaluate_script.

7. Color Contrast

To verify color contrast ratios, start by checking for native accessibility issues:

  1. Call list_console_messages with types: ["issue"].
  2. Look for "Low Contrast" issues in the output.

If native audits do not report issues (which may happen in some headless environments) or if you need to check a specific element manually, use evaluate_script with the "Check Color Contrast" snippet found in references/a11y-snippets.md.

8. Global Page Checks

Verify document-level accessibility settings often missed in component testing using the "Global Page Checks" snippet found in references/a11y-snippets.md.

Troubleshooting

If standard a11y queries fail or the evaluate_script snippets return unexpected results:

  • Visual Inspection: If automated scripts cannot determine contrast (e.g., text over gradient images or complex backgrounds), use take_screenshot to capture the element. While models cannot measure exact contrast ratios from images, they can visually assess legibility and identify obvious issues.

相关技能

Agent 工作流

Skill Creator

创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.

Agent 工作流

Clawdhub

使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.

Agent 工作流

Agent Team Orchestration

管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.

Agent 工作流

Superpowers

Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…