Debugging barriers
To find an accessibility bug, walk through the page the way a person does: can they reach it, name it, operate it, and understand the result? Tools help you search. They never finish the job.
In one minute
- Reach: put the mouse away and press Tab. Every control must get focus, in a sensible order, with a visible ring.
- Name: look at what a screen reader gets for each control: role, name, state. A button named "button" is a bug.
- Zoom: at 200% and 400% the page must reflow. No sideways scrolling to read a sentence.
- Automation finds about a third of problems. A person has to check the rest: nonsense names, wrong focus order, hidden instructions.
Think of a building inspector. A scanner can tell you a door exists and is the right width. It cannot tell you the door opens onto a brick wall. You still have to walk the route yourself, with the senses and tools your visitors use.
1. Reach it: see the tab order
The tab order is the sequence of controls you land on when you press Tab. Keyboard users, switch users and screen reader users all depend on it (WCAG 2.1.1 Keyboard, 2.4.3 Focus Order, 2.4.7 Focus Visible). Below is a small toolbar. Switch between the broken and fixed markup, then press Show tab order to number every stop. A dashed red ring means "this looks clickable, but Tab will skip it".
Step 1. Pick the markup, then press Tab inside the box yourself.
Positive tabindex values (such as 3) jump the queue and make the order unpredictable. Use
tabindex="0" only on custom widgets, and tabindex="-1" only when script will move focus there.
The best fix is almost always a native element.
2. Name it: read the accessibility tree
The accessibility tree is a second version of the page that the browser builds for assistive technology. It drops the colours and layout and keeps, for each control, three things: its role (what it is), its name (what it is called) and its state (on, off, expanded, invalid). Browser devtools show it in the Accessibility panel. Choose an element and see what lands in the tree.
Step 2. Choose a snippet.
| Property | Value |
|---|
Missing or wrong role, empty name, and stale state are the three bugs you will meet most. When a name exists but is meaningless (for example "icon-3"), no tool will flag it. You have to read it.
3. Operate it: zoom and reflow
Many people enlarge text or zoom the page. At 200% a 1280 px window behaves like 640 CSS px wide. At 400% it behaves like 320 CSS px, a small phone. WCAG 1.4.10 Reflow says content must fit at 320 CSS px without scrolling in two directions (except things like data tables and maps). The lab measures real overflow.
Step 3. Choose a layout and a zoom level.
Also test text-only enlargement (WCAG 1.4.4 Resize Text, up to 200%) and text spacing (1.4.12). If a container has a
fixed height, the text spills out or gets cut off. Use min-height and relative units.
4. Understand it: emulate preferences
People use settings you do not: grayscale, high contrast (Windows "forced colors"), reduced motion. Browser devtools
can emulate vision deficiencies, forced-colors and prefers-reduced-motion faithfully. Use them for real audits. This lab shows the idea on a small box only.
Step 4. Turn on grayscale. Which status still makes sense?
Colour only ✕ fragile
Paid / Late
Colour plus words and icon ✓ robust
Paid · settled / Late · 3 days
Loading
@media (prefers-reduced-motion: reduce) {
.pulse { animation: none; }
}
Never rely on colour alone (WCAG 1.4.1). Respect the reduced-motion setting for animation that is not essential (2.3.3 Animation from Interactions, AAA, and good practice for 2.2.2 Pause, Stop, Hide).
5. Run the manual pass, then know what automation misses
Run these in order every time the UI changes, not only before launch. Tick each one as you go.
What automated tools miss
- A name that exists but is nonsense ("button", "image1.png").
- A focus order that is possible but illogical, such as a dialog button that jumps to the footer.
- Instructions that live only in a placeholder or a colour.
- Custom widgets that expose a role and still fail the keyboard pattern for that role.
- Errors and status changes that appear on screen but are never announced.
Keep a small regression list for your product: landmarks, names, focus return, form errors and one live region. A screen reader pass on both the happy path and the error path catches what no scanner can.
Common mistakes
| You see | Why it is a problem | Fix |
|---|---|---|
| "Zero issues" from a scanner, so ship it | Scanners cannot judge names, order or keyboard patterns. | Add the manual pass. |
| Testing only with a mouse | Keyboard traps and skipped controls stay hidden. | Unplug the mouse for ten minutes. |
| Testing only at 100% | Layouts that break at 200% or 400% go unseen. | Zoom, then resize to 320 px. |
| Status shown by colour alone | Disappears in grayscale and for colour blindness. | Add text or an icon. |
| Testing only the happy path | Error messages are where most forms fail. | Submit an empty form with a screen reader on. |
- On any page you work on, press Tab once per control and count how many times it takes to reach the main content. Is there a skip link?
- Open devtools, find the Accessibility panel, and inspect your favourite icon button. What is its name?
- Zoom your browser to 400% on a real page. Do you need to scroll sideways to read?
Remember
- Audit in order: reach, name, operate, understand.
- Tab order must be logical, visible and free of traps. Prefer native elements to fix it.
- The accessibility tree is what assistive technology reads: role, name, state.
- Zoom to 400% (320 CSS px) and check for reflow. Never rely on colour alone.
- Automation narrows the search. A human with a keyboard and a screen reader finishes it.