a11y-debugging

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.