web-a11y-debugging

Diagnoses web accessibility defects using automated scanners, accessibility trees, and keyboard checks.

Updated Sep 8, 2026
One-click install
npx skills add https://github.com/pedropenha/project-skills --skill web-a11y-debugging-pedropenha
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: web-a11y-debugging
Source: https://github.com/pedropenha/project-skills/tree/main/.agents/skills/web-a11y-debugging
Command: npx skills add https://github.com/pedropenha/project-skills --skill web-a11y-debugging-pedropenha

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Accessibility barriers are hard to confirm and reproduce: automated scanners report findings without context, and manual keyboard or screen reader issues often go undetected until users complain. This Skill provides a structured debugging workflow to confirm, reproduce, and document accessibility defects with evidence. ## Core Features & Use Cases - Structured Debug Workflow: Reproduce the barrier, inspect role/name/state/value in the accessibility tree, run automation, and verify with keyboard and screen reader smoke checks. - Tooling Checklist: A repeatable checklist covering automated finding confirmation, accessibility tree inspection, keyboard contracts, screen reader smoke paths, custom CSS/JS debug rules, and CI gates. - Regression Prevention: Guidance on adding focused regression coverage and CI gates that block new Critical/High accessibility regressions. - Use Case: A scanner flags a modal dialog for missing focus management. Use this Skill to confirm the defect in the accessibility tree, verify keyboard trap behavior, run a screen reader smoke test, and produce a defect report with reproduction steps and fix direction. ## Quick Start Debug the accessibility issue on the checkout page by inspecting the accessibility tree, testing keyboard navigation, and confirming the defect with a screen reader smoke check.

Frequently Asked Questions about web-a11y-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug accessibility issues on a web page?▼

Start by reproducing the user-facing barrier, then inspect the accessibility tree for expected role, name, state, and value. Run automated scanners for common issues, verify behavior with keyboard navigation, and confirm real impact with a screen reader smoke test.

How do I verify an automated accessibility scanner finding?▼

Confirm or dismiss each automated finding with rationale by checking the accessibility tree and testing keyboard behavior manually. Automation detects many common issues but cannot replace manual verification of real user impact.

Can automated accessibility testing replace manual testing?▼

No. Automation finds many common issues but does not replace manual testing. Tool coverage differs across browsers, Shadow DOM, and widget complexity, so keyboard checks and screen reader smoke tests remain necessary.

How do I add accessibility checks to a CI pipeline?▼

Add a CI gate that blocks new Critical and High severity accessibility regressions where practical. Combine automated scanning in the pipeline with focused regression coverage for previously confirmed defects.

What are the limitations of accessibility debugging tools?▼

Tool coverage varies across browsers, Shadow DOM, and complex widgets, so scanners miss context-dependent barriers. Custom CSS/JS debug rules should be dev-only and actionable, and every report should state tool limitations and residual risk.