Accessibility

WCAG 2.2 AA is the floor, not the goal. The goal is something a tired chief of staff can read on her phone in a hotel lobby at 11pm – with the brightness turned down, two languages on the device, one hand free, and a cab outside. Accessibility is the part of the system that makes that possible. We treat it as design, not remediation.

The contract

Four guarantees the system makes – on every page, in every component, before a feature ships.

Colour & contrast

AA asks for 4.5:1 on body text and 3:1 on large text (≥ 18.66px bold, ≥ 24px regular) and on non-text UI – borders, icons, focus rings. Each semantic pair below is measured against those thresholds. Anything that fails is removed from the palette, not flagged with a warning.

Combinations to avoid – they look fine in a swatch and break the moment they touch real copy.

The approved pairings live in the colour page. When in doubt, body text is text.primary on surface.page (16.7:1) or text.brand on surface.sunken (12.4:1). Reach for tinted text only when you’ve measured it.

Keyboard

Every interactive control reaches the keyboard. The order is the visual reading order – top to bottom, left to right – and never depends on tabindex greater than 0. Esc closes overlays. Enter and Space activate. Arrow keys move within composite controls (menus, tablists, listboxes, radio groups). Shift+Tab reverses.

Every page begins with a skip-link. It’s invisible until first Tab and jumps the reader past the masthead and primary nav into the content. Keyboard users save five to ten Tab presses per page – screen-reader users save the equivalent in announcements.

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

.es-skip-link {
  position: absolute;
  inset-inline-start: var(--es-space-4);
  inset-block-start: var(--es-space-4);
  padding: var(--es-space-2) var(--es-space-3);
  background: var(--es-color-paper);
  color: var(--es-color-ink);
  border-radius: var(--es-radius-sm);
  transform: translateY(-200%);
  transition: transform var(--es-motion-state);
}
.es-skip-link:focus-visible {
  transform: translateY(0);
  box-shadow: var(--es-focus-ring);
}

Focus rings

One ring across the system, set globally on a, button, input, select, textarea, [tabindex] via :focus-visible. Teal-600, 2px stroke, 2px paper-coloured halo. Never outline: none without a replacement. Never a per-component focus colour. The full mechanics live on the states page – the rules below are the accessibility contract that page is built to satisfy.

:where(a, button, input, select, textarea, [tabindex]):focus-visible {
  outline: none;
  box-shadow: var(--es-focus-ring);
}

:focus-visible is non-negotiable. :focus (without -visible) lights up the ring on every mouse click and trains users to ignore it; :focus-visible only fires for keyboard navigation. The two pseudo-classes look the same in DevTools – they behave very differently in a real browser.

Hit targets

Pointer targets carry a non-text contrast contract too: they need enough physical area for a finger or a tremor-prone hand. WCAG 2.5.8 sets the floor at 24×24 CSS pixels. We adopt 44×44 for touch surfaces (iOS HIG, Android Material) and 24×24 only for inline icon-buttons embedded in dense tables, where 8px of clear space sits around them.

Screen readers

Naming, roles, and structure are the three things assistive tech listens for. Get those right and the rest follows.

<nav aria-label="Primary">…</nav>
<nav aria-label="Footer">…</nav>

<button aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

<label for="email">Email address</label>
<input id="email" type="email" autocomplete="email" required
       aria-describedby="email-help" />
<p id="email-help">We send eight issues a year. Cancel any time.</p>

Motion sensitivity

prefers-reduced-motion: reduce flips every duration token to 1ms and every translate distance to 0px. Components built on the motion tokens inherit this for free – which is the point. Reduced motion is not a stripped-down second design; it’s the same design, with the transitions cut.

/* From motion.css – the system enforces this layer-deep */
@media (prefers-reduced-motion: reduce) {
  :root {
    --es-duration-instant: 1ms;
    --es-duration-fast: 1ms;
    --es-duration-base: 1ms;
    --es-duration-slow: 1ms;
    --es-duration-slower: 1ms;
    --es-duration-deliberate: 1ms;
    --es-stagger-tight: 0ms;
    --es-stagger-default: 0ms;
    --es-stagger-loose: 0ms;
    --es-distance-xs: 0px;
    --es-distance-sm: 0px;
    --es-distance-md: 0px;
    --es-distance-lg: 0px;
  }
}

What we never ship, even with reduced motion respected.

Language & reading level

The voice rules live on the voice page. The accessibility layer adds three more requirements on top: programmatic language declarations, an explicit reading-age target, and a posture on which English we publish in.

<html lang="en-GB">
  <body>
    <p>
      We met at a café in
      <span lang="fr">le 11<sup>e</sup></span>
      on a Tuesday.
    </p>
  </body>
</html>

Forms accessibility

Forms are where most accessibility failures land – unlabelled fields, error messages tied to nothing, red borders carrying the entire weight of “this is wrong”. The contract is plain.

<div class="es-field">
  <label for="email">
    Email address
    <span aria-hidden="true">*</span>
  </label>
  <input
    id="email"
    type="email"
    autocomplete="email"
    required
    aria-describedby="email-help email-error"
    aria-invalid="true"
  />
  <p id="email-help" class="es-field-help">We send eight issues a year.</p>
  <p id="email-error" class="es-field-error">
    Enter an email address that includes an @.
  </p>
</div>

The full pattern lives on the forms page – this is the accessibility floor every form variant has to clear.

Testing

Before any feature ships, the designer or engineer responsible runs through this checklist. Treat each finding as a design bug, not a polish task.

Beyond AA

AA is the floor we never go beneath. AAA is the bar we reach for in two specific places.

Usage rules