| name | web-a11y-debugging |
| description | Debugs accessibility issues with automated scanners, browser accessibility trees, keyboard checks, screen reader smoke tests, custom CSS/JS rules, and CI gates. Use when triaging barriers or building accessibility validation pipelines. |
Web A11y Debugging
Debug Workflow
- Reproduce the user-facing barrier.
- Inspect role, name, state, value, and focus behavior.
- Run automation for common issues.
- Verify with keyboard and screen reader smoke checks.
- Add focused regression coverage or a CI gate where practical.
Tooling Checklist
Debugging checklist
- [ ] Automated finding is confirmed or dismissed with rationale
- [ ] Accessibility tree exposes expected role/name/state
- [ ] Keyboard behavior matches expected contract
- [ ] Screen reader smoke path confirms real impact
- [ ] Custom local rule catches recurring anti-patterns where useful
- [ ] CI gate blocks new Critical/High regressions where practical
Tooling Principles
- Automation finds many common issues but does not replace manual testing.
- Tool coverage differs across browsers, Shadow DOM, and widget complexity.
- Custom CSS/JS debug rules should be dev-only and actionable.
Output
Provide confirmed defects, evidence, reproduction steps, fix direction, tool limitations, and residual risk.
