chrome-devtools-a11y-debugging

chrome-devtools-a11y-debugging535 wordsApache-2.0Repo-owned

Use when auditing web accessibility through Chrome DevTools MCP: semantic HTML, ARIA labels, focus order, keyboard navigation, tap targets, contrast, and Lighthouse failures.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill chrome-devtools-a11y-debugging -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /chrome-devtools-a11y-debugging

Research context (evidence, not authority)

Problem: Use when auditing web accessibility through Chrome DevTools MCP: semantic HTML, ARIA labels, focus order, keyboard navigation, tap targets, contrast, and Lighthouse failures. NOT for generic page debugging, non-browser policy writing, or performance optimization. Stack / assumptions: Requires Chrome DevTools MCP 0.23.0 or compatible tools with lighthouse_audit, take_snapshot, press_key, evaluate_script, and console issue access. Comparable alternative: A general-purpose agent instruction without a scoped skill contract

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

Repo skill (hand-maintained)

Composed compose-custom-wave-1 from skills/chrome-devtools-a11y-debugging/SKILL.md with full SKILL disclosure. Do not run wagents docs generate on this file (HAND-MAINTAINED sentinel).

What It Does

Use Chrome DevTools MCP to validate what assistive technologies can see and how keyboard users move through the page. The accessibility tree is the primary source of truth; screenshots are supporting evidence.

Modes

$ARGUMENTS	Action
Empty	Ask for the URL/page and target accessibility concern
Accessibility audit	Run Lighthouse accessibility, inspect failures, then validate with snapshot and focused checks
Missing label or form issue	Use snapshot names first; use the orphan-input snippet for DOM confirmation
Keyboard/focus issue	Step through with press_key, taking snapshots after each movement
Tap target or contrast issue	Use snippets from references/a11y-snippets.md and confirm visually when needed
Modal/menu/dialog issue	Verify focus enters, remains trapped where expected, and returns after close

Critical Rules

1. Treat the accessibility tree as primary evidence for semantics and focus.
2. Use screenshots only as supporting visual evidence.
3. Do not load entire Lighthouse reports into context; extract failed audits.
4. Verify keyboard navigation with repeated key movement and fresh snapshots.
5. Report accessibility findings with observed behavior, expected behavior, and remediation.

Core Concepts

• The accessibility tree differs from the DOM. Elements hidden visually may still be exposed, and visible elements may be hidden from assistive tech.
• take_snapshot shows roles, names, heading levels, and focused elements.
• Lighthouse finds broad classes of failures; snapshots and focused checks confirm user impact.

Workflow

1. Step — Navigate to the target page and wait for the relevant UI state.

2. Step — Run lighthouse_audit in navigation mode for a baseline when page reload is safe.

3. Step — Inspect browser issues with list_console_messages using types: ["issue"] and preserved messages.

4. Step — Capture take_snapshot and check headings, landmarks, names, and order.

5. Step — Test keyboard navigation with press_key and fresh snapshots.

6. Step — Use snippets only for data missing from the accessibility tree, such as tap target dimensions or manual contrast estimates.

7. Step — Report failures with selector or uid, observed behavior, expected behavior, and remediation.

Large Report Handling

If Lighthouse writes a report, do not load the entire JSON into context. Extract failed audits with a targeted parser, for example:

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})))"

Canonical Vocabulary

Term	Meaning
Accessibility tree	Snapshot representation exposed to assistive technologies
Accessible name	Text label announced for an interactive or semantic element
Focus order	Keyboard traversal order observed through repeated snapshots
Lighthouse failure	Accessibility audit item with a failing score and remediation guidance

Validation Contract

Run from this skill directory before declaring changes complete:

python scripts/check.py

Completion criteria:

1. scripts/check.py exits 0.
2. No portable-CLI violations remain under this skill directory.

Public Metadata

Field	Value
Source Type	repo-owned
Display Source	github:wyattowalsh/agents
Source Kind	repo
Installability	portable command
Review State	reviewed
Target Agents	antigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, grok, opencode

General

Field	Value
Name	chrome-devtools-a11y-debugging
License	Apache-2.0
Version	0.23.0
Author	Google LLC

Compatibility

Field	Value
Compatibility	Requires Chrome DevTools MCP 0.23.0 or compatible tools with lighthouse_audit, take_snapshot, press_key, evaluate_script, and console issue access.

View Full SKILL.md

SKILL.md

---
name: chrome-devtools-a11y-debugging
description: 'Use when auditing web accessibility through Chrome DevTools MCP: semantic HTML, ARIA labels, focus order, keyboard navigation, tap targets, contrast, and Lighthouse failures. NOT for generic page debugging, non-browser policy writing, or performance optimization.'
license: Apache-2.0
compatibility: 'Requires Chrome DevTools MCP 0.23.0 or compatible tools with `lighthouse_audit`, `take_snapshot`, `press_key`, `evaluate_script`, and console issue access.'
metadata:
  author: Google LLC
  version: 0.23.0
---

# Chrome DevTools Accessibility Debugging

Use Chrome DevTools MCP to validate what assistive technologies can see and how keyboard users move through the page. The accessibility tree is the primary source of truth; screenshots are supporting evidence.

## Dispatch

| $ARGUMENTS | Action |
| --- | --- |
| Empty | Ask for the URL/page and target accessibility concern |
| Accessibility audit | Run Lighthouse accessibility, inspect failures, then validate with snapshot and focused checks |
| Missing label or form issue | Use snapshot names first; use the orphan-input snippet for DOM confirmation |
| Keyboard/focus issue | Step through with `press_key`, taking snapshots after each movement |
| Tap target or contrast issue | Use snippets from `references/a11y-snippets.md` and confirm visually when needed |
| Modal/menu/dialog issue | Verify focus enters, remains trapped where expected, and returns after close |

## Core Concepts

- The accessibility tree differs from the DOM. Elements hidden visually may still be exposed, and visible elements may be hidden from assistive tech.
- `take_snapshot` shows roles, names, heading levels, and focused elements.
- Lighthouse finds broad classes of failures; snapshots and focused checks confirm user impact.

## Workflow

1. Navigate to the target page and wait for the relevant UI state.
2. Run `lighthouse_audit` in `navigation` mode for a baseline when page reload is safe.
3. Inspect browser issues with `list_console_messages` using `types: ["issue"]` and preserved messages.
4. Capture `take_snapshot` and check headings, landmarks, names, and order.
5. Test keyboard navigation with `press_key` and fresh snapshots.
6. Use snippets only for data missing from the accessibility tree, such as tap target dimensions or manual contrast estimates.
7. Report failures with selector or `uid`, observed behavior, expected behavior, and remediation.

## Large Report Handling

If Lighthouse writes a report, do not load the entire JSON into context. Extract failed audits with a targeted parser, for example:

```bash
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})))"
```

## Reference File Index

| File | Content | Read When |
| --- | --- | --- |
| `references/a11y-snippets.md` | DOM snippets for labels, tap targets, contrast, and page-level checks | Snapshot and Lighthouse evidence are insufficient |
| `references/provenance.md` | Upstream source, commit, license, and adaptation notes | Before modifying this skill or auditing provenance |

## Critical Rules

1. Treat the accessibility tree as primary evidence for semantics and focus.
2. Use screenshots only as supporting visual evidence.
3. Do not load entire Lighthouse reports into context; extract failed audits.
4. Verify keyboard navigation with repeated key movement and fresh snapshots.
5. Report accessibility findings with observed behavior, expected behavior, and remediation.

## Canonical Vocabulary

| Term | Meaning |
| --- | --- |
| Accessibility tree | Snapshot representation exposed to assistive technologies |
| Accessible name | Text label announced for an interactive or semantic element |
| Focus order | Keyboard traversal order observed through repeated snapshots |
| Lighthouse failure | Accessibility audit item with a failing score and remediation guidance |

## Validation Contract

Run from this skill directory before declaring changes complete:

```bash
python scripts/check.py
```

Completion criteria:

1. `scripts/check.py` exits 0.
2. No portable-CLI violations remain under this skill directory.

Download from GitHub

Resources

Skill Catalog Browse custom and external skills.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

---

View source on GitHub