Accessibility

Accessibility (a11y) means people with disabilities can perceive, understand, navigate and operate what you build. That covers people who are blind and use a screen reader (VoiceOver, NVDA, JAWS, TalkBack), people with low vision who zoom to 400% or use high-contrast modes, colour-blind users, deaf and hard-of-hearing users who need captions, people with motor impairments who use only a keyboard, a switch or voice control, and people with cognitive disabilities who need clear language and predictable interfaces. The WHO estimates about 1.3 billion people, 16% of the world's population, have a significant disability. Add temporary and situational cases (a broken wrist, bright sunlight on a phone, a noisy train) and accessible design helps almost everyone.

The mental model for developers: the browser builds a second tree from your DOM, the accessibility tree, and assistive technology reads that tree, not your pixels. Every node in it has a role (button, link, heading), a name ("Save"), states (expanded, checked, disabled) and a value. Most accessibility work is making sure that tree tells the truth, and that everything a mouse user can do, a keyboard user can do too. This chapter checks the tree with Chrome's own computation (el.computedRole, el.computedName) in every demo.

The standard is WCAG 2.2 (Web Content Accessibility Guidelines), a W3C Recommendation since 5 October 2023 (updated 12 December 2024) and, since October 2025, also the international standard ISO/IEC 40500:2025. Its success criteria are grouped under four principles, POUR:

Each criterion has a level. A is the minimum, AA is what laws and contracts almost always require, AAA is enhanced and not expected for whole sites. Counting the W3C document itself: WCAG 2.2 has 86 success criteria, 31 at level A, 24 at AA and 31 at AAA, so AA conformance means meeting 55 of them. 4.1.1 Parsing is marked obsolete and removed. WCAG 2.2 added nine criteria: 2.4.11 Focus Not Obscured (Minimum) (AA), 2.4.12 Focus Not Obscured (Enhanced) (AAA), 2.4.13 Focus Appearance (AAA), 2.5.7 Dragging Movements (AA), 2.5.8 Target Size (Minimum) (AA), 3.2.6 Consistent Help (A), 3.3.7 Redundant Entry (A), 3.3.8 Accessible Authentication (Minimum) (AA) and 3.3.9 Accessible Authentication (Enhanced) (AAA). The demo measures one of the new ones.

.row { display: flex; align-items: center; margin-bottom: 10px; }
.row button { padding: 0; border: 0; border-radius: 4px; background: rgb(219, 234, 254); color: rgb(30, 64, 175); font: 600 12px/1 sans-serif; }
.s16 button { width: 16px; height: 16px; }
.s24 button { width: 24px; height: 24px; }
.s44 button { width: 44px; height: 44px; }
.tight { gap: 2px; }
.spaced { gap: 10px; }

<div class="row s16 tight"><button aria-label="Bold">B</button><button aria-label="Italic">I</button><button aria-label="Underline">U</button></div>
<div class="row s16 spaced"><button aria-label="Bold">B</button><button aria-label="Italic">I</button><button aria-label="Underline">U</button></div>
<div class="row s24 tight"><button aria-label="Bold">B</button><button aria-label="Italic">I</button><button aria-label="Underline">U</button></div>
<div class="row s44 tight"><button aria-label="Bold">B</button><button aria-label="Italic">I</button><button aria-label="Underline">U</button></div>

ARIA (WAI-ARIA, Accessible Rich Internet Applications) is a set of attributes (role, aria-*) that change what an element reports in the accessibility tree. That's all it does: ARIA changes semantics, never behaviour. role="button" makes a <div> announce itself as a button, but it doesn't make it focusable, doesn't make Enter or Space activate it, and doesn't make it submit a form or disable itself.

That's why the W3C's "Using ARIA" note opens with its first rule: if a native HTML element or attribute has the semantics and behaviour you need, use it instead of re-purposing an element and adding ARIA. A <button> gives you the role, the name from its content, focusability, keyboard activation, disabled, form submission and high-contrast-mode styling for free. The mental model: ARIA is a label you stick on a box. It changes what the box says it is, but if the box was empty, it's still empty.

.btn { display: inline-block; margin: 0 8px 8px 0; padding: 8px 16px; border: 0; border-radius: 6px; background: rgb(37, 99, 235); color: #fff; font: inherit; cursor: pointer; }

<button type="button" class="btn" id="native">Save</button>
<div class="btn" id="aria" role="button" tabindex="0">Save</div>
<div class="btn" id="plain">Save</div>

// What the role="button" div still needs, in JavaScript:
function makeButton(el, onActivate) {
  el.addEventListener("click", onActivate);
  el.addEventListener("keydown", (e) => {
    if (e.key === "Enter") onActivate(e);
    if (e.key === " ") e.preventDefault(); // stop Space from scrolling the page
  });
  el.addEventListener("keyup", (e) => {
    if (e.key === " ") onActivate(e); // native buttons activate on Space release
  });
}

ARIA has three kinds of attribute. A role says what something is: role="tab", role="dialog", role="switch". Properties describe relationships and characteristics that rarely change: aria-label, aria-labelledby, aria-describedby, aria-controls, aria-haspopup, aria-required. States describe the current condition and change with interaction: aria-expanded, aria-pressed, aria-checked, aria-selected, aria-current, aria-invalid, aria-disabled. (The spec's line between "states" and "properties" is fuzzy; what matters is that states must be kept in sync by your script.)

Roles come in categories: landmark roles (banner, navigation, main, complementary, contentinfo, region, search, form), document structure (heading, list, article, img, table), widget roles (button, checkbox, switch, tab, slider, menuitem) and composite widgets (tablist, menu, listbox, grid), live region roles (status, alert, log) and window roles (dialog, alertdialog). Most HTML elements already have an implicit role, which is why you rarely write roles at all. The mental model for states: the ARIA attribute is the single source of truth. Script flips the attribute; CSS styles off the attribute; assistive tech reads the attribute. Nothing can drift out of sync.

.disclosure { padding: 6px 12px; border: 1px solid rgb(148, 163, 184); border-radius: 6px; background: #fff; font: inherit; }
.disclosure[aria-expanded="false"] + .panel { display: none; }
.disclosure[aria-expanded="true"]::after { content: " ▲" / ""; }
.disclosure[aria-expanded="false"]::after { content: " ▼" / ""; }
.panel { margin: 6px 0 12px; padding: 8px; background: rgb(241, 245, 249); }
.toggle { padding: 6px 12px; border: 1px solid rgb(148, 163, 184); border-radius: 6px; background: #fff; font: inherit; font-weight: 700; }
.toggle[aria-pressed="true"] { background: rgb(30, 64, 175); color: #fff; }
nav a { margin-right: 12px; color: rgb(29, 78, 216); }
nav a[aria-current="page"] { color: rgb(30, 41, 59); font-weight: 700; text-decoration: none; border-bottom: 3px solid rgb(29, 78, 216); }

<button class="disclosure" aria-expanded="false" aria-controls="ship">Shipping details</button>
<div class="panel" id="ship">Ships in 2–3 days.</div>
<p><button class="toggle" aria-pressed="true">B</button> <span id="tip">bold is on</span></p>
<nav aria-label="Account"><a href="#p" aria-current="page">Profile</a><a href="#o">Orders</a></nav>

function toggleDisclosure(button) {
  const open = button.getAttribute("aria-expanded") === "true";
  button.setAttribute("aria-expanded", String(!open)); // CSS shows or hides the panel
}

h3, ul { margin: 0 0 8px; }

<h3 id="h" role="button">Settings</h3>
<ul id="l" role="presentation"><li id="li">One</li></ul>
<section id="s1">Unnamed section</section>
<section id="s2" aria-label="Latest news">Named section</section>
<span id="span" role="heading" aria-level="2">Not a real h2</span>

Every interactive element needs an accessible name: the text a screen reader reads ("Save, button"), voice control users speak ("click Save") and automated tests query by. A description is extra, secondary information read after the name (a hint, a format, an error). Both are computed by the browser using the W3C Accessible Name and Description Computation (accname), which checks sources in a fixed order and uses the first one that gives text.

The order, simplified: aria-labelledby (text of the referenced elements, even hidden ones) → aria-label → the native label (<label> for inputs, alt for images, <caption> for tables, <legend> for fieldsets) → the element's own text content, for roles that take their name from content (buttons, links, headings, cells) → title and, for inputs, placeholder as a last resort. The mental model: a list of name tags, checked top-down; the first tag that has writing on it wins, and the others are ignored.

.vh { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
.row { margin-bottom: 6px; }
.arrow::after { content: " →"; }
.arrow-quiet::after { content: " →" / ""; }

<div class="row"><button id="text">Save draft</button></div>
<div class="row"><button id="label" aria-label="Close dialog">×</button></div>
<div class="row"><button id="hidden"><svg aria-hidden="true" width="14" height="14"><circle cx="7" cy="7" r="6"/></svg><span class="vh">Delete message</span></button></div>
<div class="row"><button id="empty"><svg width="14" height="14"><circle cx="7" cy="7" r="6"/></svg></button></div>
<div class="row"><label for="email">Email address</label> <input id="email" type="email"></div>
<div class="row"><label>Phone <input id="wrapped" type="tel"></label></div>
<div class="row"><input id="ph" placeholder="Search products"></div>
<div class="row"><span id="billing">Billing</span> <span id="addr">address</span> <input id="lb" aria-labelledby="billing addr" aria-label="ignored"></div>
<div class="row"><label for="both">Visible label</label> <input id="both" aria-label="Different name"></div>
<div class="row"><img id="img" alt="Company logo" width="20" height="20" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='20' height='20'%3E%3Crect width='20' height='20' fill='%23334155'/%3E%3C/svg%3E"></div>
<div class="row"><a id="link" href="#p">Read more<span class="vh"> about pricing</span></a></div>
<div class="row"><button id="gen" class="arrow">Next</button> <button id="gen2" class="arrow-quiet">Next</button></div>
<div class="row"><div id="gdiv" aria-label="Order status">Shipped</div></div>

Everything a mouse can do must work from the keyboard (WCAG 2.1.1 Keyboard, level A), without traps (2.1.2), in an order that makes sense (2.4.3 Focus Order). Keyboard users press Tab and Shift+Tab to move between focusable elements, Enter to follow links and activate buttons, Space for buttons and checkboxes, and arrow keys inside composite widgets (radio groups, tabs, menus, listboxes). Screen-reader users, switch users and voice-control users all rely on the same focus mechanics.

What's focusable is decided by HTML, adjusted by tabindex. Links with href, buttons, form controls and <summary> are focusable by default. tabindex="0" adds an element to the Tab order at its DOM position. tabindex="-1" makes it focusable from script (el.focus()) but skips it when tabbing: for headings you move focus to after navigation, dialog containers and roving widgets. Positive tabindex (1, 2, 3…) jumps the element ahead of everything else in the page, in numeric order, and is almost always a bug. The mental model: the Tab order is the DOM order of everything with tabindex 0 or a natively focusable element; CSS moves boxes, not the order.

.item { display: inline-block; margin: 0 6px 6px 0; padding: 4px 8px; border: 1px solid rgb(148, 163, 184); border-radius: 4px; }
.skip { position: absolute; left: -9999px; }
.skip:focus { left: 12px; top: 12px; background: #fff; padding: 6px 10px; outline: 3px solid rgb(29, 78, 216); }

<a class="skip" href="#main">Skip to main content</a>
<button class="item" id="b">button</button>
<a class="item" id="a1" href="#x">a with href</a>
<a class="item" id="a2">a without href</a>
<div class="item" id="d0">div</div>
<div class="item" id="dz" tabindex="0">div tabindex=0</div>
<div class="item" id="dm" tabindex="-1">div tabindex=-1</div>
<button class="item" id="dis" disabled>disabled button</button>
<div inert><button class="item" id="inert">inside inert</button></div>
<h2 id="main" tabindex="-1">Main content</h2>

.bar { display: flex; gap: 8px; }
.bar button { width: 90px; padding: 6px 0; font: inherit; }
.bar .first { order: 3; }

<div class="bar">
  <button class="first">DOM 1st</button>
  <button>DOM 2nd</button>
  <button>DOM 3rd</button>
</div>

[role="toolbar"] { display: flex; gap: 4px; }
[role="toolbar"] button { padding: 6px 10px; font: inherit; }
[role="toolbar"] button:focus-visible { outline: 3px solid rgb(29, 78, 216); outline-offset: 1px; }

<div role="toolbar" aria-label="Text formatting">
  <button>Bold</button><button>Italic</button><button>Underline</button>
</div>

function rovingToolbar(toolbar) {
  const items = [...toolbar.querySelectorAll("button")];
  items.forEach((b, i) => (b.tabIndex = i === 0 ? 0 : -1));
  toolbar.addEventListener("keydown", (e) => {
    const i = items.indexOf(document.activeElement);
    if (i < 0) return;
    const keys = { ArrowRight: i + 1, ArrowLeft: i - 1, Home: 0, End: items.length - 1 };
    if (!(e.key in keys)) return;
    e.preventDefault();
    const next = (keys[e.key] + items.length) % items.length;
    items[i].tabIndex = -1;
    items[next].tabIndex = 0;
    items[next].focus();
  });
}

dialog { padding: 16px; border: 1px solid rgb(148, 163, 184); border-radius: 8px; }

<button id="open">Edit profile</button>
<dialog id="dlg" aria-labelledby="dlg-title">
  <h2 id="dlg-title">Edit profile</h2>
  <label>Name <input id="name"></label>
  <button id="close">Close</button>
</dialog>
<button id="behind">Behind the dialog</button>

A keyboard user needs to see where focus is, always: WCAG 2.4.7 Focus Visible (AA) requires a visible indicator, and WCAG 2.2 added 2.4.11 Focus Not Obscured (Minimum) (AA: the focused element isn't entirely hidden by sticky headers, cookie banners or chat widgets) and 2.4.13 Focus Appearance (AAA: the indicator is at least as large as a 2px perimeter and has 3:1 contrast between focused and unfocused states). Browsers draw a default focus ring, and the most common accessibility bug in CSS is removing it with outline: none.

:focus matches whenever an element has focus, however it got there, including a mouse click on a button. :focus-visible matches only when the browser's heuristics say a focus indicator should be shown: after keyboard navigation, always for text inputs (you need to see where you're typing), and not after a mouse click on a button. It's Baseline widely available since March 2022, and browsers' own default ring now uses it. The mental model: :focus is "has focus"; :focus-visible is "has focus, and the user is likely to need to see it". Style focus with :focus-visible, so designers stop asking to remove rings after mouse clicks.

.btn { padding: 8px 14px; border: 1px solid rgb(148, 163, 184); border-radius: 6px; background: #fff; font: inherit; }
.btn:focus-visible { outline: 3px solid rgb(29, 78, 216); outline-offset: 2px; }
.field { padding: 6px; border: 1px solid rgb(107, 114, 128); border-radius: 4px; font: inherit; }
.field:focus-visible { outline: 3px solid rgb(29, 78, 216); outline-offset: 1px; }
form:focus-within { background: rgb(239, 246, 255); }
form { padding: 8px; }

<form>
  <label>Coupon <input class="field" id="coupon"></label>
  <button class="btn" type="button" id="apply">Apply</button>
</form>

.btn:focus-visible {
  outline: 2px solid transparent; /* invisible normally, but forced colors paints it */
  box-shadow: 0 0 0 3px rgb(29 78 216 / 0.6);
}

@media (forced-colors: active) {
  .btn:focus-visible {
    outline-color: Highlight; /* a system colour keyword */
  }
}

Low-contrast text is the most common accessibility failure on the web (83.9% of home pages in WebAIM's 2026 scan). WCAG measures contrast as a ratio between the relative luminance of two colours, from 1:1 (identical) to 21:1 (black on white). 1.4.3 Contrast (Minimum) (AA) requires 4.5:1 for normal text and 3:1 for large text (at least 18pt, which is 24px, or 14pt bold, about 18.66px bold). 1.4.11 Non-text Contrast (AA) requires 3:1 for UI component boundaries (input borders, toggle tracks), focus indicators and meaningful graphics. 1.4.6 Contrast (Enhanced) (AAA) asks for 7:1.

The formula is simple enough to write from memory, and the demo's test does: convert each sRGB channel to linear light (c / 12.92 if c ≤ 0.04045, otherwise ((c + 0.055) / 1.055) ^ 2.4), weight them as L = 0.2126 R + 0.7152 G + 0.0722 B (green dominates because our eyes are most sensitive to it), then ratio = (L_lighter + 0.05) / (L_darker + 0.05). Separately, 1.4.1 Use of Color (A) says colour must never be the only way to convey information: a red border alone doesn't say "error" to someone who can't distinguish red, and links in text need more than colour to stand out.

.sw { display: inline-block; vertical-align: top; width: 150px; margin: 0 6px 6px 0; padding: 8px; background: #fff; border: 1px solid rgb(226, 232, 240); }
.a { color: #767676; }
.b { color: #777777; }
.c { color: #949494; font-size: 24px; }
.d { color: #fff; background: #2563eb; }
.e { color: #9ca3af; }
p.body { color: #1f2430; }
p.body a { color: #1d4ed8; }
.no-underline a { text-decoration: none; }
.ok, .bad { display: inline-block; width: 14px; height: 14px; border-radius: 50%; vertical-align: middle; }
.ok { background: #16a34a; } .bad { background: #dc2626; }

<div class="sw a">#767676 text</div><div class="sw b">#777777 text</div><div class="sw c">#949494 24px</div><div class="sw d">White on #2563eb</div><div class="sw e">#9ca3af text</div>
<p class="body">Read the <a href="#t">terms of sale</a> first.</p>
<p class="body no-underline">Read the <a href="#t">terms of sale</a> first.</p>
<p><span class="ok"></span> API <span class="bad"></span> Database</p>

"Hidden" means three different things, and mixing them up is a classic bug. Content can be hidden from everyone (display: none, the hidden attribute, visibility: hidden), hidden from the eye only (a visually hidden class: still read by screen readers), or hidden from assistive tech only (aria-hidden="true": still visible). And some "hiding" hides nothing: opacity: 0 makes an element invisible but it's still in the accessibility tree and still focusable.

The mental model is two audiences, eyes and the accessibility tree, and each technique switches off one, both or neither. Visually hidden text gives screen-reader users context sighted users get from layout ("Delete message 4"); aria-hidden removes decorative or duplicated content (icons next to text); display: none removes content that isn't there for anyone right now (a closed panel).

.visually-hidden {
  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
  overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0;
}
.row { margin-bottom: 6px; }
button { font: inherit; padding: 4px 10px; }

<div class="row"><button id="vh">Delete<span class="visually-hidden"> message 4</span></button></div>
<div class="row"><button id="ah"><span aria-hidden="true">★ </span>Favourite</button></div>
<div class="row"><button id="dn">Save<span style="display: none"> draft</span></button></div>
<div class="row"><button id="hd">Send<span hidden> now</span></button></div>
<div class="row"><button id="vis" style="visibility: hidden">Invisible</button><button id="op" style="opacity: 0">Transparent</button></div>
<div class="row"><span id="lbl" hidden>Close the banner</span><button id="ref" aria-labelledby="lbl">✕</button></div>
<div class="row"><button id="bad" aria-hidden="true">Hidden but focusable</button></div>

Forms are where accessibility failures cost money: a screen-reader user who can't tell which field failed, or a keyboard user who can't reach the submit button, abandons the checkout. The rules: every field has a visible label programmatically linked to it (3.3.2 Labels or Instructions; see Labels and accessible names); related controls are grouped with <fieldset> and <legend>; hints and errors are linked to the field so they're read when it gets focus; errors are identified in text (3.3.1 Error Identification, A) with a suggestion for fixing them (3.3.3 Error Suggestion, AA); and fields that collect personal data say what they are with autocomplete (1.3.5 Identify Input Purpose, AA).

The mental model: a sighted user sees the label above the field, the hint under it and the red message beside it, and connects them by position. A screen reader only reads what's programmatically connected: the label through for/id (the name), the hint and error through aria-describedby (the description), the error state through aria-invalid. If it isn't connected, it isn't there.

.field { margin-bottom: 12px; }
.field label { display: block; font-weight: 600; }
.field input { padding: 6px; border: 1px solid rgb(107, 114, 128); border-radius: 4px; font: inherit; }
.hint { margin: 2px 0; color: rgb(75, 85, 99); font-size: 14px; }
.error { margin: 2px 0; color: rgb(185, 28, 28); font-size: 14px; }
.error::before { content: "⚠ "; }
.field input[aria-invalid="true"] { border: 2px solid rgb(185, 28, 28); }
.error:empty { display: none; }

<form id="f" novalidate>
  <div class="field">
    <label for="email">Email</label>
    <p class="hint" id="email-hint">We'll send the receipt here.</p>
    <input id="email" name="email" type="email" autocomplete="email" required aria-describedby="email-hint email-error">
    <p class="error" id="email-error"></p>
  </div>
  <fieldset>
    <legend>Delivery</legend>
    <label><input type="radio" name="d" value="std" checked> Standard</label>
    <label><input type="radio" name="d" value="exp"> Express</label>
  </fieldset>
  <button>Pay</button>
</form>

function validate(form) {
  let firstInvalid = null;
  for (const input of form.querySelectorAll("input[required]")) {
    const error = document.getElementById(input.id + "-error");
    const valid = input.checkValidity();
    input.setAttribute("aria-invalid", String(!valid));
    error.textContent = valid ? "" : input.validity.valueMissing
      ? "Enter your email address."
      : "Enter an email address like name@example.com.";
    if (!valid && !firstInvalid) firstInvalid = input;
  }
  firstInvalid?.focus();
  return !firstInvalid;
}

A screen reader reads what the user moves to. When content changes somewhere else on the page (a "Saved" toast, "3 results found", a cart count, an error after an async request), a screen-reader user isn't told unless the change happens inside a live region: an element marked so that assistive technology announces changes to its content. WCAG 4.1.3 Status Messages (AA) requires status messages to be announced without moving focus.

aria-live="polite" announces when the user is idle (finishing the current sentence first); aria-live="assertive" interrupts. The roles bundle the common cases: role="status" is polite (for "Saved", result counts), role="alert" is assertive (for errors and time-critical warnings), role="log" is polite and for appended history (chat). aria-atomic="true" reads the whole region rather than just the changed part (status implies it), and aria-relevant (rarely needed) chooses which kinds of change count. The mental model: a live region is a radio speaker you install on the page in advance. Talking into it works only if the speaker was already there and switched on when you spoke; inserting a new speaker together with the message usually produces silence.

.toast, .err { min-height: 22px; margin: 6px 0; padding: 4px 8px; border-radius: 4px; }
.toast { background: rgb(220, 252, 231); color: rgb(22, 101, 52); }
.err { background: rgb(254, 226, 226); color: rgb(153, 27, 27); }
.toast:empty, .err:empty { padding: 0; background: none; }

<button id="save">Save</button>
<div class="toast" role="status" id="status"></div>
<div class="err" role="alert" id="alert"></div>
<div aria-live="polite" id="polite">2 items in cart</div>
<p>Total: <output id="total">$24.00</output></p>

// The region exists (empty) from page load; only its text changes.
function announce(region, message) {
  region.textContent = ""; // clear first, so the same message twice is still a change
  setTimeout(() => (region.textContent = message), 100);
}

Accessibility testing is layered, because no tool sees everything. Automated checkers (axe-core, which powers Lighthouse's accessibility score and most CI integrations; WAVE; Pa11y) parse the DOM and computed styles and catch machine-checkable failures: missing names, missing alt, contrast, invalid ARIA, duplicate ids, missing lang. Deque, axe's maker, reported in 2021 that automated tests found about 57% of issues by volume in its audits (it's a vendor figure, and much lower if you count WCAG criteria instead of issues). The rest needs humans: is the alt text accurate, does the focus order make sense, is the error message helpful, can you complete the checkout with only a keyboard, does it make sense in a screen reader?

The mental model is a spell checker: it finds every misspelt word and none of the sentences that make no sense. Automated tests are a floor you enforce in CI; manual testing with a keyboard and a screen reader is where you find out whether the page actually works. The demo is a small page with seven problems; below it is what axe-core actually reports.

.logo { display: block; }
.icon { width: 32px; height: 32px; padding: 0; border: 1px solid rgb(148, 163, 184); background: #fff; }
.muted { color: rgb(156, 163, 175); }
.fake-btn { display: inline-block; padding: 8px 16px; background: rgb(37, 99, 235); color: #fff; border-radius: 6px; cursor: pointer; }
.req { color: rgb(220, 38, 38); }

<header><img class="logo" width="80" height="24" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='80' height='24'%3E%3Crect width='80' height='24' rx='4' fill='%231d4ed8'/%3E%3C/svg%3E"></header>
<main>
  <h1>Checkout</h1>
  <button class="icon"><svg width="16" height="16" viewBox="0 0 16 16"><path d="M3 3l10 10M13 3L3 13" stroke="currentColor" stroke-width="2"/></svg></button>
  <p><input id="promo" placeholder="Promo code"> <span class="req">*</span></p>
  <p class="muted">Free returns within 30 days.</p>
  <p><a href="#terms">Click here</a> for the terms.</p>
  <div class="fake-btn">Pay now</div>
</main>

button-name     critical  Buttons must have discernible text                 button
color-contrast  serious   Elements must meet minimum color contrast ratio... .muted
                          "Element has insufficient color contrast of 2.53 (foreground color: #9ca3af,
                          background color: #ffffff, font size: 11.3pt (15px), font weight: normal).
                          Expected contrast ratio of 4.5:1"
image-alt       critical  Images must have alternative text                  img

24 rules passed, including: label, link-name, link-in-text-block, target-size, region, heading-order

const { screen } = await import("@testing-library/dom"); // after jsdom's window and document are global

screen.getAllByRole("button");                              // -> [<button class="icon">] (only one)
screen.getByRole("button", { name: "Pay now" });            // throws
screen.getByRole("textbox", { name: "Promo code" });        // throws
screen.getByRole("textbox").id;                             // -> "promo"
screen.getByRole("link", { name: "Click here" }).getAttribute("href"); // -> "#terms"