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.
   • 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:
   • 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 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: