On this page
Debugging Accessibility
Debug loop#
Flow
Symptom → fix
- Reproduce with keyboard or AT
- Inspect role / name / state
- Compare to intended native control
- Patch markup or behavior
- Retest the original path
Interactive demo
Inspect markup vs semantics
Choose an element
DOM / markup
<button type="button">Save</button>Accessibility tree (conceptual)
- Role
- button
- Name
- "Save"
- Notes
- Native action control. Enter and Space activate. In the a11y tree as an interactive node.
Assistive technologies read the accessibility tree—not the painted pixels alone. Same look can yield very different nodes.
Common symptoms#
Start here
- Announces as ‘button’ with no name → naming
- Cannot Tab to control → focusability / tabindex / overlay
- Looks pressed but AT disagrees → state sync
- Focus disappears in dialog → focus management