Index of every page on this site: llms.txt
All skills
chromedevtools avatar

/a11y-debugging

@bdecb63
Run it yourself

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.

  • 2 files
  • 8.6 KB
  • Updated last month
  • GitHub
Use this Skill: https://skilld.dev/gh/chromedevtools/chrome-devtools-mcp/a11y-debugging

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈58 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈697 more on demand in 1 file.

Description uses 2.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈231 characters, or 2.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.
    • Omit outputDirPath to save reports to the default temporary directory (the exact path to report.json is returned under Reports), or set outputDirPath to a directory within the workspace.
  2. Analyze the Summary:
    • In the default text output, category scores use a 0-100 scale (100 is a perfect score), followed by Passed: N and Failed: N audit counts.
    • If the server was started with --experimentalStructuredContent, inspect summary.scores[].score (0-1 scale) and summary.audits.failed in the structured content instead.
  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 from the report path returned by lighthouse_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 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, 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_screenshot to capture the element. While models cannot measure exact contrast ratios from images, they can visually assess legibility and identify obvious issues.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at bdecb63. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month

README badge

README badge for chromedevtools/chrome-devtools-mcp/a11y-debugging