Accessibility

The 30-second version

Here's a bug that ships to production every day. The checkout's “Pay” button is a <div> with a click handler. It looks perfect. It works perfectly — with a mouse. For everyone using a keyboard or a screen reader, there is no button, so there is no sale.

AccessibilityAccessibility (a11y)Making software usable by everyone, including people who use a keyboard only, a screen reader, zoom, captions or voice control. (often shortened to a11y: “a”, 11 letters, “y”) is about people who use the web differently from you. Some never touch a mouse and drive everything with the Tab key. Some can't see the screen and use a Screen readerScreen readerSoftware (VoiceOver, NVDA, JAWS, TalkBack) that reads the page aloud and lets blind and low-vision users navigate it by headings, links, landmarks and form controls., software that reads the page aloud. Some zoom the page to 400%. You'll meet them all properly in §02.

Try it yourself. Both controls below look identical. Use only your keyboard:

The difference is the element. A <button> comes with a lot built in: it's a stop on the Tab key, Enter and Space press it, and it tells assistive software “I'm a button called Pay $42”. A <div> comes with none of that. It's a plain box that happens to be painted blue.

Who uses what

“Accessibility” can sound like one special group of users. It's really many groups, each using a different tool, and each tool breaks on different mistakes. Here are the people you're building for, and what each of them needs from your code.

The general name for these tools is Assistive technologyAssistive technology (AT)Software or hardware that lets people use a computer in a different way: screen readers, screen magnifiers, voice control, switch devices, braille displays. (AT): software or hardware that lets someone use a computer in a different way.

It's not a small group, and it's not “them”

The World Health Organization estimates that around 1.3 billion people (about 1 in 6) live with a significant disability. Add the temporary cases (a broken arm, an eye infection) and the situational ones (holding a baby in one arm, bright sunlight, a loud train). At some point, almost everyone uses the web with a limitation.

Semantic HTML first

Semantic HTMLSemantic HTMLUsing the element that means what you want — button, nav, main, label, h2 — instead of generic divs, so browsers and assistive tech know what each part is and how to operate it. means picking the element that matches what the thing is: a button for an action, a link for navigation, a heading for a heading. The opposite is “div soup”: everything is a <div> or <span>, and CSS and JavaScript fake the rest.

The browser turns your HTML into a second, simpler tree for assistive technology: the Accessibility treeAccessibility treeA second tree the browser builds from the DOM, holding only what assistive technology needs: each node's role, name, states and value. Screen readers read this tree, not your pixels or CSS.. You'll see how it's built in §04. For now, look at what it contains for the same checkout written both ways. Toggle between them:

<div class="header">
  <div class="logo">ShopCo</div>
  <div class="nav">
    <div onclick="go('/cart')">Cart</div>
    <div onclick="go('/help')">Help</div>
  </div>
</div>
<div class="content">
  <div class="title">Checkout</div>
  <div class="field">
    <div>Email</div>
    <input type="email">
  </div>
  <div class="check">
    <div class="box" onclick="toggle()"></div> Save my details
  </div>
  <div class="btn" onclick="pay()">Pay $42</div>
</div>

The div-soup version looks identical on screen. But to a screen reader it's two lines of anonymous text and one mystery text box. Nothing tells it which words are links, which is the heading, or that “Pay $42” can be pressed.

Button or link?

These two get mixed up more than any others. The rule is short:

<!-- Action pretending to be a link -->
<a href="#" onclick="addToCart()">Add to cart</a>

<!-- Navigation pretending to be a button -->
<div class="btn" onclick="location = '/cart'">
  View cart
</div>

<!-- Action → button -->
<button type="button" onclick="addToCart()">
  Add to cart
</button>

<!-- Navigation → link -->
<a href="/cart">View cart</a>

Headings and landmarks: the page's table of contents

Screen reader users rarely listen to a page top to bottom. They pull up a list of headings (in NVDA, the H key jumps to the next one) and skim, the way you'd skim bold text. So:

• Use <h1>–<h6> for real headings, in order. One <h1> for the page title, <h2> for sections, <h3> inside those. Don't skip levels because <h4> “looks the right size”. Change the size with CSS instead.
• Don't use a heading tag just to make text big or bold.

LandmarksLandmarkA large region of the page with a known purpose — banner (site header), navigation, main, contentinfo (footer), search, complementary — that screen reader users can jump between, like chapters in a book. are the big regions of a page. The elements below create them automatically. The “landmark role” column is what the browser tells screen readers each region is (roles are explained in §04). aria-label is an attribute that gives an element a name to be announced (§04 and §05 cover it):

Every input needs a label

Clicking a <label> focuses its input, and the label's text becomes the input's name. That's what a screen reader reads. There are two ways to connect them:

<!-- explicit: for="…" points at the input's id -->
<label for="email">Email</label>
<input id="email" type="email" autocomplete="email">

<!-- implicit: wrap the input -->
<label><input type="checkbox"> Save my details</label>

The accessibility tree: name, role, state

The browser already builds the DOMDOMThe Document Object Model: the browser's tree of objects that represents the page. Every button, input and div is a DOM node you can attach event listeners to. to draw the page. From the DOM it builds a second, slimmer tree: the Accessibility treeAccessibility treeA second tree the browser builds from the DOM, holding only what assistive technology needs: each node's role, name, states and value. Screen readers read this tree, not your pixels or CSS.. Purely decorative wrappers, hidden elements and aria-hidden content are left out. Each node that's kept gets four properties:

Step through how one checkbox travels from HTML to speech:

1<label>
2  <input type="checkbox" checked>
3  Email me order updates
4</label>

The browser talks to assistive technology through the operating system's Accessibility APIAccessibility APIThe operating system's interface that apps use to describe their UI to assistive technology: UI Automation on Windows, NSAccessibility on macOS, AT-SPI on Linux. The browser translates its accessibility tree into it., never through your pixels. That's why the tree is all that matters to a screen reader.

The step that matters most: the role came free with the element. Every HTML element has an Implicit roleImplicit roleThe role an HTML element has without any ARIA: <button> is a button, <a href> is a link, <nav> is navigation, <h2> is a heading.. <button> is a button, <a href> is a link, <input type="checkbox"> is a checkbox. A <div> has the role “generic”, which assistive technology treats as meaningless.

How the accessible name is chosen

A control can get its name from several places. When more than one is present, the browser follows a fixed priority order. For a text input, highest priority first:

1. aria-labelledby="id1 id2": joins the text of the elements with those ids.
2. aria-label="…": a string you write that is never shown on screen.
3. A <label>, connected with for/id or by wrapping the input.
4. The title attribute, which is also a mouse-hover tooltip.
5. The placeholder, the grey hint text inside the field.

Buttons and links also take their name from their content (the text inside them, or an image's alt). That step comes after aria-label and before title. Play with the ladder:

<h2 id="h">Find products</h2>
<label for="q">Search</label>
<input id="q" type="search"
       placeholder="e.g. headphones">

A few results worth remembering (each one checked in headless Chromium):

Descriptions: the second line

A name should be short (“Password”). Extra help goes in the Accessible descriptionAccessible descriptionExtra help text announced after a control's name, role and state, usually connected with aria-describedby — for example a password hint or an error message., which screen readers read after the name, role and state:

<label for="pw">Password</label>
<input id="pw" type="password" aria-describedby="pw-hint">
<p id="pw-hint">At least 8 characters.</p>
<!-- NVDA (roughly): "Password, edit, protected, At least 8 characters." -->

ARIA: powerful, and easy to make worse

ARIAARIAAccessible Rich Internet Applications: HTML attributes (role, aria-label, aria-expanded…) that tell assistive technology what a custom widget is and what state it's in. Native HTML elements need it far less. attributes come in three kinds:

The first rule of ARIA

The W3C's own guide states it plainly: if a native HTML element already has the meaning and behaviour you need, use it instead of adding ARIA. Its corollary is just as famous: no ARIA is better than bad ARIA. WebAIM's yearly scan of the top million home pages keeps finding that pages with ARIA have more detected errors than pages without it, on average.

Why can ARIA make things worse? Because it overrides what the browser would have said, and nothing checks that your claims are true:

When ARIA is the right tool: states the HTML can't express

The legitimate job for ARIA is describing custom widgets and changing state that HTML has no element for. The classic example is a “show more” toggle. A <button> gives you the role, the focus and the keyboard. aria-expanded adds the one thing HTML can't express: “open” or “closed”.

<div class="toggle" onclick="toggle()">
  Shipping details ▾
</div>
<div class="panel" style="display:none">
  Ships in 2 working days.
</div>

function Disclosure({ title, children }) {
  const [open, setOpen] = useState(false);
  const panelId = useId();                 // unique id, safe with several instances
  return (
    <>
      <button
        type="button"
        aria-expanded={open}               // ← the state, kept in sync with React state
        aria-controls={panelId}            // ← "this button controls that element"
        onClick={() => setOpen(!open)}
      >
        {title}
      </button>
      <div id={panelId} hidden={!open}>{children}</div>
    </>
  );
}

Native HTML has a ready-made version too: <details><summary>Shipping details</summary>…</details>. It needs no JavaScript or ARIA at all. Use it when you don't need custom animation or control from code.

Live regions: announcing changes without moving focus

When something changes somewhere other than where focus is (“Added to cart”, “3 results”, “Saved”), a screen reader user won't know unless you tell them. A Live regionLive regionAn element whose text changes are announced by screen readers even though focus is somewhere else — made with role="status", role="alert" or aria-live. Used for toasts, cart counts and “12 results” messages. is an element whose text changes the screen reader reads out automatically.

<div class="cart-msg">…</div>

Keyboard and focus

Keyboard focusKeyboard focusThe single element that currently receives key presses. Tab moves it forward, Shift+Tab backwards, and a visible outline (the focus ring) should show where it is. is like the cursor in a text editor, but for the whole page: key presses go to whichever element has it. These are the keys every keyboard user expects to work:

What's in the tab order

The Tab orderTab orderThe sequence in which Tab visits focusable elements. By default it follows the order of elements in the HTML source, not where CSS places them on screen. contains links that have an href, buttons, inputs, selects and textareas, unless they're disabled. Divs, spans, headings and an <a> without href are skipped. The tabindextabindexAn HTML attribute that changes focusability. tabindex="0" puts an element in the Tab order at its source position; "-1" makes it focusable only from code; positive numbers jump the queue (avoid them). attribute changes this:

Try them in the sandbox. The numbers are the order the browser will use:

The order is real browser behaviour. In headless Chromium, a page with Help (tabindex=1), Promo (tabindex=3) and four normal controls was visited as Help → Promo → Logo → Search → Buy → Card. Positive values always come first, smallest number first. Then everything else follows in source order.

Never hide the focus ring (style it instead)

outline: none with nothing to replace it is one of the most common accessibility failures on the web. Without a visible focus indicator, a keyboard user is driving blind. Tick “Hide the focus ring” in the lab above and try to find where you are.

People remove it because they dislike the ring appearing after a mouse click. :focus-visible:focus-visibleA CSS pseudo-class that matches the focused element only when a focus ring is useful — typically after keyboard use, not after a mouse click. Style focus rings with it instead of :focus. solves exactly that. The browser applies it after keyboard navigation, but not after a mouse click on a button. (Text fields still show it when clicked, because you need to see where you're typing.) Checked in Chromium: clicking a button → :focus-visible false; tabbing to it → true.

/* Remove the default ring only where the browser wouldn't show it anyway… */
button:focus:not(:focus-visible) { outline: none; }

/* …and draw a clear one for keyboard users. */
:focus-visible {
  outline: 3px solid #22d3ee;   /* ≥ 3:1 contrast against the background (§08) */
  outline-offset: 2px;          /* a gap, so it's visible on any button colour */
}

Skip links

Every page on a typical site starts with the same 20–40 header links. A keyboard user would have to Tab through all of them on every page before reaching the content. A Skip linkSkip linkA link at the very start of a page, usually visible only when it has focus, that jumps to the main content — so keyboard users don't have to Tab through the whole header on every page. is the first focusable thing on the page. It stays hidden until it receives focus, then jumps straight to <main>:

<body>
  <a class="skip-link" href="#main">Skip to main content</a>
  <header>… 30 links …</header>
  <main id="main" tabindex="-1">  <!-- -1: so focus can land here -->
    <h1>Checkout</h1>
  </main>
</body>

Try it on almost any government website: load a page and press Tab once. Landmarks (§03) give screen reader users a second way to skip, but sighted keyboard users have only the skip link. It's what the WCAGWCAGThe Web Content Accessibility Guidelines from the W3C: testable rules (contrast, keyboard access, labels…) at levels A, AA and AAA. AA is the usual legal and company target. rule “Bypass Blocks” is about.

Managing focus: dialogs and menus

Modal dialogs

A Modal dialogModal dialogA dialog that blocks the rest of the page until it's answered (Confirm / Cancel). While it's open, the page behind must be unreachable by mouse, keyboard and screen reader. asks a question and blocks everything else until you answer. For keyboard and screen reader users, “blocks everything else” has four concrete parts:

1. Move focus in when it opens, usually to the first button, or to the safest one, like Cancel.
2. Keep focus in while it's open. Tab must not reach the page behind it. This is a Focus trapFocus trapKeeping Tab and Shift+Tab cycling inside one region — usually an open modal dialog — so keyboard users can't wander into the page hidden behind it..
3. Escape closes it.
4. Return focus to the button that opened it, so the user continues where they left off.

The native <dialog> element, opened with showModal(), does all four for you. Compare it with the usual hand-made overlay:

Here's what Chromium actually did with <dialog> + showModal() in our test:

• Focus moved to Cancel, the first focusable element inside.
• Tab cycled Cancel → Delete → (out to the browser's own toolbar) → Cancel. It never reached the page.
• Escape closed it, and focus went back to the Delete account… button.
• The rest of the page became inertinertAn HTML attribute that makes a whole part of the page unclickable, unfocusable and invisible to assistive technology. Opening a <dialog> with showModal() makes the rest of the page inert automatically.. A click on a background button did nothing, and the accessibility tree contained only the dialog.

function ConfirmDelete({ open, onClose, onConfirm }) {
  const ref = useRef(null);
  const titleId = useId();

  useEffect(() => {
    const d = ref.current;
    if (open && !d.open) d.showModal();   // ← modal: page behind becomes inert
    if (!open && d.open) d.close();       //   close() puts focus back on the opener
  }, [open]);
  // Every way of closing (Cancel, Escape, the parent setting open=false) goes through
  // d.close(), which fires the "close" event once → onClose runs exactly once.

  return (
    <dialog ref={ref} aria-labelledby={titleId}
            onClose={onClose}>            {/* fires on Escape too */}
      <h2 id={titleId}>Delete your account?</h2>
      <p>This can't be undone.</p>
      <button type="button" onClick={() => ref.current.close()}>Cancel</button>
      <button type="button" onClick={onConfirm}>Delete</button>
    </dialog>
  );
}

Composite widgets: one Tab stop, arrow keys inside

Some widgets contain many items: a menu, a toolbar, tabs, a listbox. Putting every item in the Tab order would mean ten presses of Tab to get past one menu. The convention instead:

• Tab moves into the widget and out of it. The whole group is one Tab stop.
• Arrow keys move between items inside it. Home and End jump to the first and last item.

The usual way to build this is a Roving tabindexRoving tabindexA technique for groups like menus, toolbars and tab lists: exactly one item has tabindex="0" (so the group is a single Tab stop) and the rest have "-1". Arrow keys move the 0 — and the focus — between items.. Exactly one item has tabindex="0" (so Tab lands there), and every other item has tabindex="-1". When an arrow key is pressed, you move the 0 to the next item and call .focus() on it. Try the menu below and watch the attributes change:

The keys and roles above aren't made up. They come from the ARIA Authoring Practices GuideARIA Authoring Practices Guide (APG)The W3C's catalogue of patterns for custom widgets (menu button, tabs, combobox, dialog, …): which roles and states to use and exactly which keys must do what, with working examples., the W3C's catalogue of widget patterns. Before building any custom widget (tabs, combobox, tree view, slider), look up its pattern there. It tells you every key and every ARIA attribute users will expect.

// The core of roving tabindex (simplified from the widget above)
const [active, setActive] = useState(0);
const items = useRef([]);          // the <li> DOM elements

useEffect(() => { items.current[active]?.focus(); }, [active]); // (the real one only while open)

function onKeyDown(e) {
  const last = ACTIONS.length - 1;
  if (e.key === "ArrowDown")    setActive((i) => (i === last ? 0 : i + 1)); // wrap around
  else if (e.key === "ArrowUp") setActive((i) => (i === 0 ? last : i - 1));
  else if (e.key === "Home")    setActive(0);
  else if (e.key === "End")     setActive(last);
  else return;                  // any other key: leave it alone
  e.preventDefault();           // ← handled: stop the arrows/Home/End also scrolling the page
}

<ul role="menu" onKeyDown={onKeyDown}>
  {ACTIONS.map((a, i) => (
    <li key={a} role="menuitem"
        ref={(el) => (items.current[i] = el)}
        tabIndex={i === active ? 0 : -1}>   {/* ← the roving part */}
      {a}
    </li>
  ))}
</ul>

Seeing it: contrast, colour, zoom, motion

Contrast is a number, not a matter of taste

WCAGWCAGThe Web Content Accessibility Guidelines from the W3C: testable rules (contrast, keyboard access, labels…) at levels A, AA and AAA. AA is the usual legal and company target. defines a Contrast ratioContrast ratioHow far apart two colours are in brightness, from 1:1 (identical) to 21:1 (black on white). WCAG AA asks for at least 4.5:1 between normal text and its background. between two colours. It's computed from each colour's Relative luminanceRelative luminanceHow bright a colour looks to the human eye, on a scale from 0 (black) to 1 (white). It's computed from the red, green and blue values, with green counting the most because our eyes are most sensitive to it.: how bright the eye perceives it, from 0 for black to 1 for white. The recipe:

1. Turn each red, green and blue value (0–255) into a 0–1 number, then undo the screen's “gamma” curve. Values ≤ 0.04045 are divided by 12.92; larger ones become ((c + 0.055) / 1.055) ^ 2.4. You don't need to know why: this just converts the stored number into actual light.
2. Luminance L = 0.2126·R + 0.7152·G + 0.0722·B. Green counts most because our eyes are most sensitive to it.
3. Ratio = (L_lighter + 0.05) / (L_darker + 0.05). The result runs from 1:1 (same colour) to 21:1 (black on white).

Worked example: #999999 grey on white. 153/255 = 0.6 → about 0.319 after step 1, and since R = G = B, L ≈ 0.319. White has L = 1. Ratio = (1 + 0.05) / (0.319 + 0.05) ≈ 2.85:1, nowhere near the 4.5 needed. (axe displays it as 2.84 because it cuts the number off at two decimals, and the checker below does the same. The pass/fail test itself uses the exact value, and WCAG allows no rounding up: a ratio of 4.499 fails.)

The thresholds (WCAG 2.2, level AA):

Don't rely on colour alone

About 1 in 12 men and 1 in 200 women have some form of colour-vision deficiency, most often trouble telling red from green. Some users override all page colours with a high-contrast theme, and printouts are often greyscale. So colour can reinforce a message, but never be the only way to get it.

The two lists below use a red and a green that look almost the same to someone with deuteranopia, a strong form of red-green colour blindness. The simulation uses a standard published colour model, so treat it as an approximation:

Common fixes: an icon plus text (“✕ failed”), underlined links inside paragraphs (not just a different colour), and error messages in words, not only a red border (§09). For charts, use patterns or direct labels, not just a colour legend.

Zoom and reflow

Low-vision users zoom. WCAG asks for two things:

• Text can be resized to 200% without anything getting cut off or overlapping.
• ReflowReflow (WCAG 1.4.10)The rule that content must still work at 320 CSS pixels wide — about 400% zoom on a typical laptop — without scrolling sideways to read lines of text.: at 320 CSS px wide, about 400% zoom on a 1280 px screen, content fits in one column with no sideways scrolling.

The habits that get you there, mostly covered in CSS layout:

• Size text in rem, not px. rem follows the user's browser font-size setting.
• Never set maximum-scale=1 or user-scalable=no in the ViewportViewportThe visible area of the page in the browser window. On phones the meta viewport tag tells the browser to use the device width instead of pretending to be a desktop. meta tag. That blocks pinch-zoom on phones.
• Let containers grow with their text: avoid fixed height on things that contain text.
• Test by zooming your own app to 400%.

Respect “reduce motion”

Users who get dizzy from motion (§02) can turn on “Reduce motion” in their OS settings. Browsers expose it to CSS as the Media queryMedia queryA CSS rule that applies only under some condition, e.g. @media (min-width: 768px) for wider screens or (prefers-reduced-motion: reduce). prefers-reduced-motionprefers-reduced-motionA CSS media query that matches when the user has asked their operating system for less animation (for example because motion makes them dizzy). Your CSS and JS can check it and tone animations down.:

.card { transition: transform 300ms ease; }
.card:hover { transform: scale(1.05); }

@media (prefers-reduced-motion: reduce) {
  .card { transition: none; }          /* ← no zoom animation */
  html  { scroll-behavior: auto; }     /* ← no smooth-scrolling jumps */
}

“Reduce” doesn't have to mean “remove”. A quick fade is usually fine. What triggers symptoms is large movement: zooms, parallax, spinning, full-screen slides. Also, anything that moves by itself for more than 5 seconds (a carousel, an animated banner) needs a pause button, whatever the user's settings say.

Forms and error messages

Forms are where accessibility failures cost real money: sign-ups, checkouts, bookings. They combine everything so far: names (§04), descriptions, states (§05) and focus management (§07). Try both versions with the keyboard and watch the screen reader preview:

In the typical version, a screen reader user hears nothing at all after pressing Create account. Focus stays on the button, and the red borders are invisible to them. In the accessible version, focus moves to the first broken field, and its name, “invalid” state and error message are read in one go.

The anatomy of an accessible field

const id = useId();                          // unique per form instance (§05)
const hintId = `${id}-hint`, errId = `${id}-err`;

<form noValidate onSubmit={handleSubmit}>    {/* ← turn off the browser's own error bubbles */}
  <label htmlFor={id}>Email</label>
  <p id={hintId}>We'll send your receipt here.</p>
  <input
    id={id}
    type="email"
    autoComplete="email"                     // ← browsers & password managers can fill it
    required                                 // ← still announced as "required"
    aria-invalid={Boolean(error)}            // ← announced as "invalid entry"
    aria-describedby={error ? `${hintId} ${errId}` : hintId}  // ← hint + error read after the name
  />
  {/* ← the error as text, not just a red border: */}
  {error && <p id={errId}>✕ {error}</p>}
  <button type="submit">Create account</button>
</form>

What each piece does for whom:

Where to put focus after a failed submit

Two common patterns, both fine:

1. Focus the first invalid field. Its name, “invalid” and its error (through aria-describedby) are read straight away. Simple, good for short forms. This is what the demo does.
2. An error summary at the top for long forms: a heading like “There are 3 problems”, with a list of links that each jump to a broken field. Move focus to the summary, using tabindex="-1" on its container and .focus(). GOV.UK's design system made this pattern famous.

Groups of controls: fieldset and legend

Radio buttons and checkbox groups need a name for the group as well as for each option. Otherwise a screen reader user hears “Express, radio button, 1 of 2” without the question they're answering:

<fieldset>
  <legend>Delivery speed</legend>        <!-- the group's name -->
  <label><input type="radio" name="speed" value="std"> Standard (3–5 days)</label>
  <label><input type="radio" name="speed" value="exp"> Express (next day)</label>
</fieldset>
<!-- NVDA (roughly): "Delivery speed, grouping, Standard (3–5 days), radio button, not checked, 1 of 2" -->

Native radio groups also come with arrow-key navigation built in. That's the roving-tabindex behaviour from §07, with no code to write.

Testing: axe, keyboard, screen readers

Automated: axe-core

axe-coreaxe-coreA free, open-source JavaScript library from Deque that checks a page against accessibility rules and lists the violations. It powers Lighthouse's accessibility audit and many browser extensions and test helpers. is the engine behind most automated accessibility checks. That includes the accessibility score in LighthouseLighthouseGoogle's page-auditing tool, built into Chrome DevTools. It scores performance, accessibility (using a subset of axe-core's rules), best practices and SEO. (Chrome DevTools → Lighthouse), the axe DevTools browser extension, and test helpers for Playwright, Cypress and Jest. It loads into the page, inspects the live DOM, the computed styles and the accessibility tree, and returns a list of rule violations.

We ran it for real on three small pages. Compare what it reported with what it missed:

<html>
<div class="header">
  <img src="logo.png">
  <div onclick="go('/cart')">Cart</div>
</div>
<div class="title">Checkout</div>
<input type="email" placeholder="Email">
<!-- .hint is #999 on white: -->
<p class="hint">We'll send your receipt here.</p>
<button class="icon"><svg>…</svg></button>
<div class="btn" role="button" tabindex="0"
     onclick="pay()">Pay $42</div>
<div aria-hidden="true">
  <a href="/terms">Terms</a>
</div>
<h3>Order summary</h3>
<ul><div>1 × Headphones</div></ul>

Look at the “did not report” box for the div soup. The page can't be used with a keyboard at all, and the only WCAG failure axe reports is a missing label. axe can't know that a div with a click handler was meant to be a button. Deque, axe's maker, estimates that automated tests find roughly half of all accessibility issues (their study of real audits put it at 57% by issue count). Other estimates are lower. Either way, a clean report is where testing starts, not where it ends.

Put it in your test suite

The cheapest time to catch a regression is in CICI (continuous integration)A server that builds your code and runs its tests automatically on every push (GitHub Actions, GitLab CI, …), so mistakes are caught minutes after they're made. A flaky test there blocks everyone's merges., before merge. With Playwright and the @axe-core/playwright package:

import { test, expect } from "@playwright/test";
import { AxeBuilder } from "@axe-core/playwright";

test("checkout has no detectable WCAG A/AA violations", async ({ page }) => {
  await page.goto("/checkout/");
  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])  // ← add "wcag22aa" for the 2.2 rules
    .analyze();
  expect(results.violations).toEqual([]);
});

test("Pay button is reachable with Tab and works with Enter", async ({ page }) => {
  await page.goto("/checkout/");
  const pay = page.getByRole("button", { name: "Pay $42" });   // ← finds it by role + name
  const isFocused = () => pay.evaluate((el) => el === document.activeElement);
  for (let i = 0; i < 20 && !(await isFocused()); i++) {
    await page.keyboard.press("Tab");                          // ← reach it the way users do
  }
  await expect(pay).toBeFocused();
  await page.keyboard.press("Enter");
  await expect(page.getByRole("heading", { name: "Thank you" })).toBeVisible();
});

Why press Tab instead of calling pay.focus()? Because .focus() from code also works on an element with tabindex="-1", which Tab can never reach (§06). A test that calls .focus() would pass for exactly the bug it should catch.

We ran this file for real (Playwright 1.63, headless Chromium) against two tiny pages. Against the semantic checkout from §03, with a submit handler that shows “Thank you”:

Running 2 tests using 1 worker

  ✓  1 tests/checkout.a11y.spec.js:4:5 › checkout has no detectable WCAG A/AA violations (625ms)
  ✓  2 tests/checkout.a11y.spec.js:12:5 › Pay button is reachable with Tab and works with Enter (285ms)

  2 passed (1.8s)

Against a broken version whose Pay “button” is <div role="button" tabindex="-1"> and whose email input has no label, both tests fail. The second failure, trimmed:

  ✘  1 tests/checkout.a11y.spec.js:12:5 › Pay button is reachable with Tab and works with Enter (2.4s)

    Error: expect(locator).toBeFocused() failed
    Locator:  getByRole('button', { name: 'Pay $42' })
    Expected: focused
    Received: inactive
        21 × locator resolved to <div class="btn" role="button" tabindex="-1" onclick="…">Pay $42</div>
           - unexpected value "inactive"

The axe test failed on the same page with rule label (critical, “Form elements must have labels”).

getByRole(…) is the best habit in that test. It finds elements the way a screen reader does, by role and accessible name, so the test fails if someone swaps the button for a div. Testing Library (screen.getByRole("button", { name: /pay/i })) works the same way in unit tests. If a test can't find your control by role and name, a screen reader user can't either.

Manual: the keyboard walkthrough (10 minutes, every feature)

Put the mouse away and go through the feature:

1. Tab from the address bar. Is there a skip link? Does focus go through the page in a sensible order?
2. Can you always see focus? Watch for it disappearing behind sticky headers or on dark backgrounds.
3. Can you operate everything? Buttons with Enter and Space, menus with arrows, dialogs with Escape.
4. Do you ever get stuck, or lose focus to the top of the page after an action?
5. After a dialog closes or an item is deleted, is focus somewhere sensible?
6. Zoom to 200% and 400%. Does anything overlap, get cut off, or need sideways scrolling?

Manual: screen reader basics

You don't need to be an expert. Learn a handful of commands on the screen reader you have, and listen to your feature once:

The NVDA key is Insert by default. You can also set Caps Lock as the NVDA key, which is popular on laptops. What to listen for: does every control say a sensible name, role and state? Do the headings list and landmarks list make sense on their own? Are changes like “Added to cart” or errors announced?

Staff level: WCAG, the law, component libraries, React

WCAG 2.2 AA, in practice

WCAGWCAGThe Web Content Accessibility Guidelines from the W3C: testable rules (contrast, keyboard access, labels…) at levels A, AA and AAA. AA is the usual legal and company target. is organised in layers. Four principles, POURPOURWCAG's four principles: content must be Perceivable (you can sense it), Operable (you can use it), Understandable (you can make sense of it) and Robust (it works with assistive technology).. Under them, guidelines. Under those, testable success criteriaSuccess criterion (WCAG)One testable WCAG rule, numbered like 1.4.3 (Contrast), with a level: A, AA or AAA. A page either meets it or fails it. (SC), each with a number and a level: A (the bare minimum), AA (the usual target in contracts and laws), and AAA (aspirational, not required across whole sites). Version 2.2 (October 2023) added nine criteria and removed one: 4.1.1 Parsing, which modern browsers made obsolete.

Most of what this page taught maps onto a handful of these: 1.1.1, 1.3.1, 1.4.3, 2.1.1, 2.4.3, 2.4.7, 3.3.1 and 4.1.2 account for the bulk of real-world failures. In WebAIM's yearly scan of the top million home pages, low-contrast text, missing image alt text, unlabelled form inputs, empty links and empty buttons are the most common detected errors, year after year.

The law (a general picture, not legal advice)

Laws differ by country and change often, so treat this as orientation and ask your legal team for specifics. The pattern is similar almost everywhere: WCAG level AA is the technical yardstick.

• United States. Websites of businesses open to the public have been the subject of thousands of lawsuits a year under the Americans with Disabilities Act (ADA). Courts and settlements usually point at WCAG 2.x AA. Federal agencies and their suppliers must meet Section 508, which incorporates WCAG 2.0 AA. A 2024 Department of Justice rule set WCAG 2.1 AA for state and local government websites, with compliance dates originally set for April 2026 and April 2027 depending on the size of the government. Check the current status, since dates like these can be changed.
• European Union. Public-sector sites have had requirements since the Web Accessibility Directive (2016). The European Accessibility Act has applied since 28 June 2025 to many private-sector products and services, including e-commerce, banking, e-books and passenger transport. Its technical standard, EN 301 549, builds on WCAG 2.1 AA.
• Elsewhere. The UK (Equality Act and public-sector regulations), Canada, Australia, Japan and others have similar rules, mostly pointing at WCAG.

Enterprise and government buyers often ask for an accessibility conformance report, usually written in the VPAT format. It's a criterion-by-criterion statement of how your product meets WCAG. Writing an honest one is far easier if you've been testing all along.

Building an accessible component library

A Component libraryComponent library (design system)A shared set of ready-made UI components — Button, Dialog, Menu, Tabs — that every team in a company builds with, so an accessibility fix made once reaches every product. is where accessibility scales. What the good ones do:

1. Semantics inside, no escape hatch needed. <Button> renders a <button>. <Link> renders an <a href>. A <Dialog> uses <dialog> or implements every part of the APG dialog pattern. Product teams should never need div onClick.
2. Make the accessible path the easy path. Make the name required: <IconButton icon={TrashIcon} label="Delete invoice" /> should fail type-checking (or at least warn) without label. Have <TextField label="Email" error={msg} /> wire up id, htmlFor, aria-describedby and aria-invalid internally, so nobody can forget them.
3. Document the keyboard contract for each component: “Tabs: ←/→ move, Home/End jump, Tab leaves”. Test it with Playwright, like §10.
4. Contrast in the tokens. If every text and background token pair is checked once, screens can't drift (§08).
5. Or build on a headless library that already implements the APG patterns and leaves the styling to you: React Aria, Radix UI, Headless UI, Ariakit. Writing a correct combobox from scratch takes weeks. Reusing one takes an afternoon.

React specifics

React apps are usually single-page appsSingle-page app (SPA)A web app that loads one HTML page and then changes the view with JavaScript as you navigate, instead of loading a new page from the server each time., and that breaks one thing the browser normally does for free. On a classic page load, the screen reader announces the new page title and focus starts at the top. On a client-side route change, the URL and the content change, but focus stays on the link you clicked, which may not even exist any more. Nothing is announced.

The common fix is to move focus to the new page's main heading after each navigation:

import { useEffect, useRef } from "react";
import { useLocation } from "react-router";

// Render once, in the layout that wraps every page.
export function RouteFocus() {
  const { pathname } = useLocation();
  const prev = useRef(pathname);

  useEffect(() => {
    if (prev.current === pathname) return;  // first load (and StrictMode's re-run): leave focus alone
    prev.current = pathname;
    const h1 = document.querySelector("main h1");
    if (h1) {
      h1.tabIndex = -1;                     // ← focusable from code, not a Tab stop (§06)
      h1.focus();                           // ← screen reader reads the new page's heading
    }
  }, [pathname]);

  return null;
}

Also update the page title on every route. React 19 lets any component render <title>Checkout · ShopCo</title>, and React moves it into <head> for you. Some teams prefer a polite live region (§05) that says “Navigated to Checkout” instead of moving focus. Either is fine, as long as something tells the user the page changed.

Two more React habits:

• Fragments keep the structure valid. A <ListItem> component that returns <div><li>…</li></div> breaks the list. axe's list rule in §10 is exactly that bug. Return <li> directly, or a fragment <>…</> when you need several siblings. The same goes for table rows and <dl> pairs. See React's model.
• useId() for every id/ARIA pairing (§05), never hard-coded ids. Two copies of a component with id="email" give both labels the same target, and one field ends up without a name.

Pitfalls gallery

Nine mistakes that show up in almost every audit, each with the fix.

<div className="btn" onClick={save}>Save</div>

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

<button onClick={remove}>
  <TrashIcon />
</button>

<button onClick={remove} aria-label="Delete invoice">
  <TrashIcon aria-hidden="true" />
</button>

*:focus { outline: none; }

:focus-visible {
  outline: 3px solid #22d3ee;
  outline-offset: 2px;
}

<aside class="drawer closed" aria-hidden="true">
  <a href="/settings">Settings</a>
</aside>

<aside class="drawer closed" inert>
  <a href="/settings">Settings</a>
</aside>

<input type="email" placeholder="Email">

<label for="email">Email</label>
<input id="email" type="email" placeholder="name@example.com">

<img src="q3.png">
<img src="divider.png" alt="divider image">

<img src="q3.png" alt="Revenue up 40% in Q3">
<img src="divider.png" alt="">

Check yourself

Commit to an answer before you click. Each explanation points back to the section that covers it.

<div className="btn" onClick={pay}>Pay $42</div>

<button aria-label="Close dialog">X</button>

<button tabindex="2">A</button>
<button>B</button>
<button tabindex="1">C</button>
<div tabindex="0">D</div>
<div tabindex="-1">E</div>

{saved && <div role="status">Saved!</div>}

<div aria-hidden="true">
  <button>Buy now</button>
</div>

<span role="button" tabindex="0" onclick="save()">Save</span>

Cheat sheet