a11y-debugging
π―SkillHelps find and fix accessibility problems on web pages, so people using screen readers or keyboards can use them. It drives a Chrome browser to run audits and check labels, focus, color contrast and tap target size.
Installation
npx skills add chromedevtools/chrome-devtools-mcp --skill a11y-debuggingRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/a11y-debuggingInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/a11y-debugging/ - All projects
~/.claude/skills/a11y-debugging/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub β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.
- Run the audit:
- Set
modeto"navigation"to refresh the page and capture load issues. - Omit
outputDirPathto save reports to the default temporary directory (the exact path toreport.jsonis returned underReports), or setoutputDirPathto a directory within the workspace.
- Set
- Analyze the Summary:
- In the default text output, category scores use a 0-100 scale (100 is a perfect score), followed by
Passed: NandFailed: Naudit counts. - If the server was started with
--experimentalStructuredContent, inspectsummary.scores[].score(0-1 scale) andsummary.audits.failedin the structured content instead.
- In the default text output, category scores use a 0-100 scale (100 is a perfect score), followed by
- Review the Report (CRITICAL):
- Parsing: Do not read the entire file line-by-line. Use a CLI tool like
jqor a Node.js one-liner to filter for failures from the report path returned bylighthouse_audit:# Extract failing audits with their details (replace with report.json path from tool response) node -e "const r=require('<path/to/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
selectorandsnippetof failing elements without loading the full report into context.
- Parsing: Do not read the entire file line-by-line. Use a CLI tool like
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.
- Navigate to the page.
- Use
take_snapshotto capture the accessibility tree. - Check Heading Levels: Ensure heading levels (
h1,h2,h3, etc.) are logical and do not skip levels. The snapshot will include heading roles. - Content Reordering: Verify that the DOM order (which drives the accessibility tree) matches the visual reading order. Use
take_screenshotto 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
- Locate buttons, inputs, and images in the
take_snapshotoutput. - Ensure interactive elements have an accessible name (e.g., a button should not just say
""if it only contains an icon). - Orphaned Inputs: Verify that all form inputs have associated labels. Use
evaluate_scriptwith the "Find Orphaned Form Inputs" snippet found in references/a11y-snippets.md. - Check images for
alttext.
5. Focus & Keyboard Navigation
Testing "keyboard traps" and proper focus management without visual feedback relies on tracking the focused element.
- Use the
press_keytool with"Tab"or"Shift+Tab"to move focus. - Use
take_snapshotto capture the updated accessibility tree. - Locate the element marked as focused in the snapshot to verify focus moved to the expected interactive element.
- 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, use the "Check Color Contrast" snippet found in references/a11y-snippets.md with evaluate_script.
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_screenshotto capture the element. While models cannot measure exact contrast ratios from images, they can visually assess legibility and identify obvious issues.
More from this repository8
Lets your AI coding tool open and control a real Chrome browser. It can test pages, find bugs, take screenshots, and check how fast a site loads.
Chrome DevTools for coding agents
Chrome DevTools MCP is an official MCP server from the Chrome DevTools team that lets AI coding agents control and inspect a live Chrome browser.
Lets your AI agent control and inspect a Chrome browser to debug web pages. It can open pages, click and fill in forms, take screenshots, check page speed, read styles, and watch network traffic, through the chrome-devtools-mcp tool.
Helps you find out why the main content of a web page appears slowly, and how to fix it. It uses Chrome DevTools tools to record a page load, measure each stage and point to the slowest part.
Lets you control the Chrome browser from your terminal with simple commands. You can open pages, click, type into forms and take page snapshots, or put these steps in shell scripts to automate browser tasks.
Helps fix setup problems when your AI assistant cannot connect to Chrome through Chrome DevTools MCP, a tool that lets AI control the browser. It reads your config file, matches common error messages and walks you through fixes step by step.
Helps find and fix memory leaks in JavaScript and Node.js apps, where an app keeps using more and more memory. It uses Chrome DevTools tools to take and compare memory snapshots and find what is holding on to memory.