Requires the chrome-devtools-mcp server to be running. Start with a Lighthouse accessibility audit to get a baseline score and failing elements. Then investigate specific issues: semantics and heading structure, labels and forms, keyboard navigation, tap target sizes, and colour contrast.

Accessibility (a11y) Debugging

Uses Chrome DevTools MCP for accessibility debugging and auditing based on web.dev guidelines.

Core Concepts

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 — what assistive technologies "see" — making it the most reliable source of truth for semantic structure.

Reading web.dev documentation: Append .md.txt to a web.dev URL to fetch the clean, raw markdown version. Example: https://web.dev/articles/accessible-tap-targets.md.txt.

Workflow Patterns

1. Automated Audit (Lighthouse)

Start by running a Lighthouse accessibility audit for a comprehensive baseline:

1. Set mode to "navigation" to refresh the page and capture load issues.
2. Set outputDirPath (e.g., /tmp/lh-report) to save the full JSON report.
3. Parse failures with:

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

2. Browser Issues & Audits

Use list_console_messages with types: ["issue"] and includePreservedMessages: true to check for native accessibility audits.

3. Semantics & Structure

1. Navigate to the page.
2. Use take_snapshot to capture the accessibility tree.
3. Check heading levels — ensure they do not skip levels.
4. Verify DOM order matches visual reading order.

4. Labels, Forms & Text Alternatives

1. Locate buttons, inputs, and images in the take_snapshot output.
2. Ensure interactive elements have an accessible name.
3. Verify all form inputs have associated labels.
4. Check images for alt text.

5. Focus & Keyboard Navigation

1. Use press_key with "Tab" or "Shift+Tab" to move focus.
2. Use take_snapshot to capture the updated accessibility tree.
3. Locate the focused element 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

According to web.dev, tap targets should be at least 48×48 px with sufficient spacing. Use evaluate_script to measure tap target sizes.

7. Colour Contrast

1. Call list_console_messages with types: ["issue"].
2. Look for "Low Contrast" issues.
3. If not detected automatically, use evaluate_script to check specific elements manually.