The accessibility checklist

What it means

Landmarks give a screen reader a table of contents for the page: a user can jump straight to the navigation, or to the main content, without listening through everything before it. A page built entirely from div elements offers no such jumps, so every visit starts at the top and walks forward.

What the fix looks like

document.querySelectorAll('header,nav,main,aside,footer')
// exactly one <main>; each repeated <nav> needs aria-label

Usually breaks when

A component library wraps everything in div, or a layout gains a second main during a refactor and nobody notices.

What it means

Heading level is an outline, not a type scale. Screen reader users pull up a list of headings to understand and navigate a page, so a jump from h2 to h4 reads as a missing section, and an h3 chosen because it "looked right" puts content in the wrong place in that outline.

What the fix looks like

[...document.querySelectorAll('h1,h2,h3,h4,h5,h6')]
  .map(h => h.tagName + ' ' + h.textContent.trim())

Usually breaks when

A design hands over "small bold label" and the nearest heading level is used to get the size.

What it means

The lang attribute tells assistive technology which pronunciation rules to use. Without it a screen reader reads English with the user default voice, which can render an English page in a Hindi phonology — technically speech, practically noise.

What the fix looks like

<html lang="en">
  <p>The dish was <span lang="fr">déjà vu</span>.</p>

Usually breaks when

A template ships with lang hard-coded to one language and the site later gains a second.

What it means

The title is announced on load and is what a user sees in a long list of tabs or in browser history. Put the distinguishing part first: "Invoices — Acme" beats "Acme — Invoices" when the tab is 90 pixels wide.

What the fix looks like

// on route change
document.title = `${page.name} — Acme`;

Usually breaks when

A single-page app changes the view without touching the title, so every route announces the same words.

What it means

Native elements carry relationships that CSS cannot: a list announces how many items it has, a data table lets a user read a cell together with its row and column headers. Rebuild either from div and that structure is gone, leaving a flat run of text.

What the fix looks like

<table>
  <caption>Revenue by quarter</caption>
  <tr><th scope="col">Quarter</th><th scope="col">Revenue</th></tr>

Usually breaks when

A CSS grid gives the layout the designer wanted, and the semantics are never added back.

What it means

Assistive technology and keyboard focus follow the DOM. CSS can reorder what the eye sees without touching it, so a sidebar that reads last but appears first will be reached last — the two orders drift apart silently and only ever surface in testing.

Usually breaks when

A responsive layout uses order or grid-area to rearrange columns at one breakpoint and not another.

What it means

A native button is focusable, announces its role, fires on both Enter and Space, and works with voice control — all of it for free. A div with a click handler has none of that, and reproducing it takes four extra attributes people routinely forget one of.

What the fix looks like

// no
<div onClick={save}>Save</div>

// yes
<button type="button" onClick={save}>Save</button>

Usually breaks when

A designer asks for something that "should not look like a button", and the semantics get removed along with the styling.

What it means

A trap is any place focus can enter and cannot leave with the keyboard alone. It is the most severe failure on this list, because the user is not merely blocked from one feature — they are stuck on the page, with no way forward and no way back.

What the fix looks like

dialog.addEventListener('keydown', (e) => {
  if (e.key === 'Escape') close();   // and return focus to the trigger
});

Usually breaks when

A focus trap is added to a modal for correctness, and the release path is never wired to Escape or to the close button.

What it means

The focus ring is the keyboard user cursor. Remove it and they are typing blind — they cannot tell which control Enter is about to activate. :focus-visible solves the reason it is usually removed, by showing the ring for keyboard focus and not after a mouse click.

What the fix looks like

:focus-visible {
  outline: 2px solid currentColor;
  outline-offset: 2px;
}
/* never `outline: none` without a replacement */

Usually breaks when

A reset stylesheet strips outlines site-wide on day one and nobody puts anything back.

What it means

Tab order comes from the DOM. A positive tabindex jumps the element to the front of the whole page order, which breaks the sequence everywhere else — one tabindex="3" quietly reorders every control on the page around it.

What the fix looks like

tabindex="0"   // put it in the natural order
tabindex="-1"  // focusable by script only
tabindex="3"   // almost always a mistake

Usually breaks when

Someone reaches for tabindex to fix one control and reorders the page.

What it means

A client-side route change replaces the content but leaves focus wherever it was — often on a link that no longer exists, which drops focus to the top of the document with no announcement. The fix is to move focus deliberately and to say what changed.

What the fix looks like

// after render
headingRef.current.focus();   // h1 with tabindex="-1"
// on dialog close
triggerRef.current.focus();

Usually breaks when

The router animates the transition and focus is forgotten because the page looks like it moved.

What it means

Without a skip link, every visit to every page starts by tabbing through the whole navigation. The common failure is subtle: the link scrolls the page but focus stays behind, so the next Tab lands back in the menu the user was escaping.

What the fix looks like

<a class="skip" href="#main">Skip to main content</a>
<main id="main" tabindex="-1">

Usually breaks when

The target is a div with no tabindex, so the browser scrolls but does not move focus.

What it means

Small targets are hard to hit for anyone with a tremor, on a moving train, or using a stylus. WCAG 2.2 added a 24px floor, and it can be satisfied either by making the target bigger or by giving it enough clear space that a missed tap does not hit its neighbour.

What the fix looks like

.icon-btn { min-inline-size: 24px; min-block-size: 24px; }
/* or leave 24px of clear space between targets */

Usually breaks when

A dense toolbar shrinks on mobile, where the targets need to be larger rather than smaller.

What it means

The label is what a screen reader announces when focus lands on a field, and what voice control users say to reach it. A placeholder disappears the moment someone types, taking the only description of the field with it — which is worst for the people most likely to need it back.

What the fix looks like

<label for="email">Email</label>
<input id="email" type="email" autocomplete="email">

<!-- or, visually hidden -->
<input aria-label="Search">

Usually breaks when

A minimal design removes the labels, and placeholders are pressed into service as a substitute.

What it means

An error has to say three things: that something is wrong, which field it is wrong on, and what to do about it. A red border says the first, vaguely, to people who can see red — the association and the instruction have to be programmatic and in words.

What the fix looks like

<input id="email" aria-invalid="true" aria-describedby="email-err">
<p id="email-err">Enter an email address, like [email protected]</p>

Usually breaks when

Validation is implemented visually first, and the ARIA wiring is left as a follow-up ticket.

What it means

The autocomplete attribute names what a field collects using a fixed vocabulary, which lets browsers fill it and lets some assistive technology show a familiar icon in place of a word. It is one of the rare criteria where doing the accessible thing measurably lifts conversion.

What the fix looks like

<input name="tel" type="tel" autocomplete="tel">
<input name="postcode" autocomplete="postal-code">

Usually breaks when

A custom input component drops unrecognised attributes on the way to the DOM.

What it means

A radio button announces its own label but not the question it answers. The legend supplies that question, so "Standard delivery, radio, 1 of 3" becomes "Delivery method: standard delivery, radio, 1 of 3".

What the fix looks like

<fieldset>
  <legend>Delivery method</legend>
  <label><input type="radio" name="ship"> Standard</label>
</fieldset>

Usually breaks when

fieldset is hard to style, so it gets replaced by a div and a heading.

What it means

Client-side validation usually re-renders the form in place. Nothing about that re-render is announced, so a screen reader user presses Submit, hears nothing, and concludes the button is broken.

What the fix looks like

<div role="alert">2 problems stop this form being submitted</div>
// or move focus to the summary, then to the first bad field

Usually breaks when

The error summary is rendered before it exists in the DOM, so the live region has nothing to announce.

What it means

For anything that costs money, forms a contract, or deletes data, WCAG asks for one of three protections: the action can be undone, the input is checked and correctable, or the user gets a confirmation step before it is final.

Usually breaks when

A one-click flow is added for speed and the confirmation step is what gets cut.

What it means

Alt text answers one question: what would a sighted person get from this image that they would not get from the surrounding text? If the answer is nothing, alt="" is the correct, deliberate value — an empty alt is a decision, a missing alt attribute is an oversight, and screen readers treat them differently.

What the fix looks like

<img src="q3.png" alt="Revenue fell 12% in Q3, the first drop since 2019">
<img src="flourish.svg" alt="">

Usually breaks when

A CMS makes alt a required field, so authors type the filename to get past it.

What it means

Text baked into a picture is invisible to search, translation, reader modes and text-spacing overrides, and it blurs when someone zooms. A code screenshot in documentation cannot be copied, read aloud, or searched for the error message it shows.

Usually breaks when

A designed quote or a code sample is exported as PNG because it was quicker than building it.

What it means

Captions carry dialogue and the sounds that matter; a transcript makes the same content searchable and skimmable. Machine captions get names, jargon and figures wrong at exactly the moments those things matter most, so they are a starting point, not a deliverable.

Usually breaks when

Auto-captions are enabled once, and nobody reads them again.

What it means

Audio description narrates what is shown but not said — a diagram, an on-screen figure, a demonstration performed in silence. Where a video is planned well, the narration covers this and no separate track is needed.

Usually breaks when

A product demo shows the interface while the voiceover says "as you can see here".

What it means

Autoplaying audio competes with a screen reader speaking, and the two cannot be separated by ear. The stop control has to come early in the focus order, because reaching it is exactly what the noise makes difficult.

Usually breaks when

A background video ships muted, and a later change adds a soundtrack.

What it means

Two failures with one cause. An icon-only button with no name announces as "button" and nothing else. An icon left visible to assistive technology beside a text label gets announced twice, or announced as its filename.

What the fix looks like

<button aria-label="Delete"><svg aria-hidden="true">…</svg></button>
<button><svg aria-hidden="true">…</svg> Delete</button>

Usually breaks when

An icon component is used both ways and hard-codes one of them.

What it means

Contrast is measured between the text and what is actually behind it. Translucent overlays, tinted cards and gradients all change that background, so the number in the design token is frequently not the number on screen — a colour can pass on white and fail on the card it lives in.

What the fix looks like

/* 4.5:1 body, 3:1 for 24px or 18.5px bold */

Usually breaks when

A grey is chosen against white, then reused on a cream surface where it no longer passes.

What it means

Text is not the only thing that has to be seen. The boundary that tells you where an input begins, the toggle that shows a setting is on, the line in a chart — all need 3:1 against what surrounds them. Hairline borders are the usual casualty of this rule.

Usually breaks when

A very light border is chosen for elegance, at about 1.2:1.

What it means

If removing all colour removes the information, colour was doing the work alone. The fix is a second cue that survives greyscale: an underline, an icon, a shape, a direct label, a pattern.

Usually breaks when

A status system is built on red, amber and green, and the shapes are added only for the icons.

What it means

Contrast is usually checked once, in the resting state. Every other state is a different pair of colours, and a hover that swaps a background without swapping the text is the classic way a passing button becomes unreadable at the moment it is being used.

Usually breaks when

A hover fills the button with the brand colour and the label stays white.

What it means

Dark mode is a second palette, not a filter, and needs its own measurements. Forced-colors mode goes further: the operating system replaces your colours wholesale, so anything carried by a background image, a shadow or a gradient simply disappears.

What the fix looks like

@media (forced-colors: active) {
  .card { border: 1px solid CanvasText; }
}

Usually breaks when

A focus ring is drawn with box-shadow, which forced-colors mode removes.

What it means

Simulation shows what a palette becomes for the three common types of colour-vision deficiency. Palettes that look distinct on a swatch sheet often collapse into two colours once they are small, adjacent and rendered as chart series.

Usually breaks when

The palette is tested and the interface built from it is not.

What it means

Vestibular disorders make large motion genuinely sickening: parallax, zooming transitions and scroll-jacking can cause nausea and migraine that outlast the visit. The operating system already knows the preference; honouring it costs one media query.

What the fix looks like

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: .01ms !important;
    transition-duration: .01ms !important;
  }
}

Usually breaks when

The query covers CSS transitions, and a JavaScript scroll animation is left running.

What it means

Flashing between about 3 and 55 times a second can trigger a seizure in people with photosensitive epilepsy. This is the one item on the list where the consequence of getting it wrong is a medical emergency rather than an inconvenience.

Usually breaks when

A glitch effect or a strobing loader is added for style.

What it means

Anything that moves, blinks or updates by itself for more than five seconds needs a way to stop it. Motion beside text pulls attention away mid-sentence, and content that rewrites itself while being read is impossible to follow.

Usually breaks when

A hero carousel advances on a timer with no controls at all.

What it means

Where inactivity can destroy data, the user has to be warned how long they have — before they start, not after it has gone. People who take longer to read or type are exactly the people timeouts hit.

Usually breaks when

A session length is set for security and the front end never learns about it.

What it means

Every control has to tell assistive technology three things: what it is called, what kind of thing it is, and what state it is in. The hard part is the third — the state has to be updated every time it changes, and a stale aria-expanded is worse than none, because it actively lies.

What the fix looks like

<button aria-expanded="false" aria-controls="menu">Filters</button>
// on toggle: btn.setAttribute('aria-expanded', String(open))

Usually breaks when

The attribute is set in the initial render and never touched again.

What it means

A tab list responds to arrow keys, Home and End; a menu closes on Escape and returns focus to its trigger. These conventions are documented in the ARIA Authoring Practices Guide, and users of assistive technology have learned them — inventing your own means they have to learn yours.

Usually breaks when

A component gets the roles right and the keyboard handling never gets written.

What it means

A message that appears without taking focus is invisible to a screen reader unless it lands inside a live region. The container has to exist in the DOM before the text arrives, or there is nothing there to observe the change.

What the fix looks like

<!-- render the container empty, then fill it -->
<div role="status" aria-live="polite">Saved</div>

Usually breaks when

The whole toast including its live region is inserted at once, so nothing is announced.

What it means

aria-hidden removes an element from the accessibility tree without removing it from the focus order. Focus can land somewhere that, as far as the screen reader is concerned, does not exist — so the user hears nothing at all and cannot tell what happened.

What the fix looks like

// hide from everyone, not just from AT
el.hidden = true;   // or inert on the container

Usually breaks when

A modal hides the background with aria-hidden and leaves the links behind it tabbable.

What it means

Screen reader users often pull up a list of every link on the page to navigate. In that list there is no surrounding paragraph, so eleven "read more" links become eleven identical entries with no way to tell them apart.

What the fix looks like

<a href="/q3">Read the Q3 report</a>
<!-- or keep the visible text and extend it -->
<a href="/q3">Read more<span class="visually-hidden"> about Q3</span></a>

Usually breaks when

A card component takes a fixed call to action and is reused down a whole index page.

What it means

At 400% zoom a 1280px desktop viewport becomes 320px of usable width. Content must reflow into that single column: having to scroll sideways to read every line of every paragraph is what the criterion exists to prevent.

Usually breaks when

A fixed-width element — a table, an embed, a long unbroken string — sets a floor the layout cannot go below.

What it means

Text must double in size without content being cut off or made unusable. The usual failure is a container with a fixed height: the text grows, the box does not, and the last line is clipped or hidden entirely.

What the fix looks like

/* let it grow */
.card { min-block-size: 120px; }   /* not height: 120px */

Usually breaks when

A card grid is given a fixed height so the rows line up.

What it means

Some users apply a stylesheet that opens up spacing to make text readable, particularly people with dyslexia. WCAG names exact values that must survive without losing content — which mostly means not fixing the height of anything that holds text.

What the fix looks like

* { line-height: 1.5 !important;
    letter-spacing: .12em !important;
    word-spacing: .16em !important; }
p { margin-block-end: 2em !important; }

Usually breaks when

A component sets an exact height to match a design, and a fifth word arrives.

What it means

Many users have a device fixed in one orientation — mounted on a wheelchair, on a stand, on an arm. Locking the interface to the other one makes it unusable rather than merely awkward.

Usually breaks when

A mobile app-style layout assumes portrait and locks it in the manifest.

What it means

Tabbing forward scrolls the next control into view, and a sticky header can sit exactly where it lands — so the element has focus, is scrolled to, and is completely covered. Keyboard users are left typing into something they cannot see.

What the fix looks like

/* keep the focused element clear of the sticky header */
:target, :focus-visible { scroll-margin-block-start: 6rem; }

Usually breaks when

A sticky header is added late, long after the focus order was tested.

What it means

Automated rules reliably find missing alt attributes, unlabelled fields, contrast failures and broken ARIA references. That is roughly a third of what matters, and it is the third that is tedious to find by hand — so it belongs in CI, freeing review for the two thirds that need judgement.

What the fix looks like

# fail the build, do not just report
npx axe-ci $URL --exit-code

Usually breaks when

The job is added as advisory and stays permanently amber.

What it means

The cheapest high-yield test there is. Most focus traps, invisible focus rings, unreachable controls and broken dialogs surface within a few minutes of trying to complete one real task without a pointer.

Usually breaks when

It is nobody specific job, so it happens the week before an audit.

What it means

Screen readers differ from each other and from what the accessibility tree suggests they will do. Testing one real pairing end to end teaches more than reading three specifications, and it is the only way to hear what your live regions actually announce.

Usually breaks when

The team tests with a browser extension that reports the tree rather than speaking it.

What it means

A finding without evidence gets argued about; a finding with a marked-up screenshot and a criterion number gets fixed. It also gives you an audit trail with a date on it, which is what a procurement question actually asks for.

Usually breaks when

Findings are recorded in a spreadsheet with a column for the page and none for the proof.

What it means

A checklist encodes what previous failures taught someone else. It cannot tell you that a flow is technically conformant and still exhausting, or that a pattern is correct and unfamiliar. Only the people who use this software with assistive technology every day can.

Usually breaks when

Conformance is treated as the goal rather than as the floor.