Frontend, chapter 01 of 09
Accessibility
WCAG 2.2 AA as the baseline: semantic HTML first, keyboard and focus, contrast, reduced motion, and testing that goes beyond what automated tools can catch.
About 1 in 6 people worldwide live with a significant disability, and far more are situationally impaired at any moment: a broken arm, a phone in direct sunlight, a noisy train. Accessibility isn't a feature for a niche audience; it's whether a large share of your users can use the product at all.
It's part of "done", not a later pass. Retrofitting means redesigning components people already depend on, while building it in mostly means using the platform the way it was designed, so most of what follows costs nothing if it's done first.
The Baseline: WCAG 2.2 AA#
I target WCAG 2.2 at level AA for everything I ship. Level A alone leaves real barriers, like insufficient contrast, in place. AAA can't be met by all content, so it's an aspiration for specific pages, not a baseline. AA is achievable everywhere without compromising design, and it's the level regulators, procurement teams and courts reference.
WCAG 2.2 added criteria worth knowing by name (what's new):
| Criterion | Level | In practice |
|---|---|---|
| 2.4.11 Focus Not Obscured (Minimum) | AA | Sticky headers and cookie banners can't completely cover the focused element |
| 2.5.7 Dragging Movements | AA | Anything done by dragging has a single-pointer alternative |
| 2.5.8 Target Size (Minimum) | AA | Pointer targets are at least 24 by 24 CSS pixels, or spaced as if they were |
| 3.2.6 Consistent Help | A | Help links appear in the same place across pages |
| 3.3.7 Redundant Entry | A | Don't make people retype what they already entered in the same flow |
| 3.3.8 Accessible Authentication (Minimum) | AA | No cognitive tests to log in; allow paste and password managers |
Semantic HTML First#
The browser already knows how to make a <button> focusable, keyboard-operable and announced correctly. A <div> with a click handler knows none of that.
- Use the element that means what you're building:
<button>for actions,<a href>for navigation,<nav>,<main>,<label>,<table>for tabular data, headings in order. - ARIA only when HTML can't do it. ARIA changes what's announced, not how anything behaves.
role="button"on a<div>makes a screen reader say "button", but the div still ignores Enter and Space and can't receive focus: a broken button that claims to work. That's why the W3C's first rule of ARIA is to use a native element whenever one exists. - Custom widgets (tabs, comboboxes, dialogs) follow the ARIA Authoring Practices Guide patterns, including their keyboard behavior.
- The visible text is the name. Someone using voice control says what they see ("click preview"), so an accessible name has to contain the visible label, ideally starting with it (2.5.3 Label in Name). An
aria-labelthat rephrases the text breaks that; add context as visually hidden text after the visible text instead. Watch for adjacent spans with no space between them: "Download" and "PDF" side by side read as "DownloadPDF".
Keyboard and Focus#
Everything usable with a mouse is usable with a keyboard alone.
- Logical tab order, following the visual order. No positive
tabindex. - Visible focus, always. Never remove outlines without a replacement.
:focus-visibleshows focus for keyboard users without flashing it on every mouse click. - Dialogs trap focus while open and return it to the trigger when closed.
Escapecloses them. - A skip link to the main content on pages with long navigation.
- Clear the sticky header. A sticky header covers whatever scrolls to the top of the viewport: the focused element, and every
#anchora heading link jumps to (2.4.11 Focus Not Obscured).scroll-padding-toponhtml, a little taller than the header, fixes both at once. - Scrollable regions take focus. A wide table or code block that scrolls sideways has to be reachable by keyboard, or its hidden columns are mouse-only. Give it
tabindex="0",role="region"and a label, but only while it actually overflows: a tab stop on every table that fits costs keyboard users more than it helps.
Color and Contrast#
- Text: at least 4.5:1 against its background, 3:1 for large text (18pt, or 14pt bold).
- UI components and graphics: at least 3:1 for borders of inputs, focus indicators, icons and chart marks that carry meaning.
- Never color alone. Errors get an icon and text, links get an underline or another cue, charts get labels or patterns.
- Check every theme. A palette that passes in dark mode can fail in light mode. See Design Tokens & Theming.
- Check every surface. A token is checked against each surface it sits on, not only the page background: cards, hover rows, selected rows and tinted badges are all darker (or lighter) than the page, and that's where a borderline color fails.
- Opacity is a contrast trap. Muted text made with opacity (
text-muted/70), and text set in a color meant for borders, usually lands under 4.5:1. Dim with a text token that's checked, not with transparency. - Syntax highlighting themes fail out of the box. Popular code themes set comments and punctuation well under 4.5:1. Remap just the failing token colors per theme (Shiki's
colorReplacementsdoes this), and test the colors the highlighter actually emits against each code background, so a theme upgrade can't quietly bring them back.
Motion#
Respect prefers-reduced-motion. Animations that move, zoom or parallax get a reduced or static alternative. Nothing flashes more than three times a second.
Forms#
Forms are where most accessibility failures cost someone a task: unlabeled inputs, errors only shown in red, a form cleared on failure. Forms & Validation covers labels, attached error messages and autocomplete in full.
Images and Media#
- Meaningful images get
alttext that says what the image communicates, not what it looks like. - Decorative images get
alt="", so screen readers skip them. - Video has captions; audio has transcripts.
Testing#
Automated tools are necessary and nowhere near sufficient. They can tell that an image has alt text, not whether it describes the image; that a button has a name, not whether the name makes sense. axe-core, the engine behind most of them, reports finding about 57% of WCAG issues on average, so a clean report means the easy half is done. The rest takes a person:
- Automated checks in CI with axe, failing the build on new violations (wiring it into the suite). Pick one page per route pattern from the sitemap, so a new kind of page is covered the day it ships, and run it in every theme and at 320px width: most contrast failures only show in one theme, and most overflow and target-size failures only at the narrow width. Once, when you adopt it, crawl every URL: content-driven pages (a table, a code block, a long word) fail in ways their template doesn't. Block your error reporter's ingestion while it runs, or the crawl files its own issues.
- A keyboard pass on every new flow: unplug the mouse and finish the task.
- A screen reader pass on new components: VoiceOver on macOS and iOS, NVDA on Windows.
- Zoom to 200% and check at 320px width: content reflows, nothing overlaps or gets cut off.
It's the Law, Too#
In the US, the Department of Justice's position is that the ADA applies to the websites of businesses open to the public (ADA.gov guidance). In the EU, the European Accessibility Act has applied since 28 June 2025 and covers e-commerce and other consumer services. Building to WCAG 2.2 AA puts you on the right side of both. The litigation against online stores, and what it asks for, is in Accessibility and ADA Litigation.
References#
Specifications
- W3C: Web Content Accessibility Guidelines (WCAG) 2.2, success criteria, contrast ratios and conformance levels
- W3C: What's New in WCAG 2.2, the nine criteria added in 2.2
- W3C: Using ARIA, the rules of ARIA use, starting with native HTML first
- W3C: Understanding Label in Name (2.5.3), why the accessible name contains the visible label
- W3C: Understanding Focus Not Obscured (2.4.11), sticky headers and focused content
Reference
- W3C: ARIA Authoring Practices Guide, keyboard and ARIA patterns for custom widgets
- MDN: prefers-reduced-motion, detecting the reduced-motion preference
- MDN: scroll-padding-top, keeping scrolled-to content clear of a sticky header
- Shiki: Color Replacements, remapping a theme's token colors
- Deque: axe-core, the automated testing engine and what share of issues it catches
In practice
- WHO: Disability and health, 1.3 billion people, about 1 in 6, with significant disability
- ADA.gov: Guidance on Web Accessibility and the ADA, how the ADA applies to websites
- European Commission: European Accessibility Act, scope of the EU requirements