/web-accessibility-web-accessibility

name: web-accessibility-web-accessibility
description: WCAG, ARIA, keyboard navigation

Accessibility

> **Quick Guide:** Most of accessibility is settled by choosing the right element: a `<button>` arrives with focus, keyboard activation and a role that a `<div>` needs a dozen lines to fake. What the element cannot give you is the rest — a name for every control, a visible focus indicator, 4.5:1 contrast on text, an announcement when content changes, and information never carried by colour alone. Target WCAG 2.2 Level AA. Automated checks find roughly half the failures, so a keyboard pass is not optional.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — skip links, landmarks, semantic structure, button versus link
• [examples/forms.md](examples/forms.md) — labels, error handling, required fields, the listbox contract
• [examples/focus.md](examples/focus.md) — dialogs, focus trapping and restoration, focus indicators
• [examples/color.md](examples/color.md) — contrast, colour-independent status, link styling
• [examples/tables.md](examples/tables.md) — headers, captions, sortable columns
• [examples/touch-targets.md](examples/touch-targets.md) — target size and spacing
• [examples/screen-reader.md](examples/screen-reader.md) — visually hidden text, decorative content
• [examples/testing.md](examples/testing.md) — automated auditing, role-based queries, the manual pass
• [reference.md](reference.md) — WCAG 2.2 criteria, accessible-name rules, audit rule IDs, screen readers

---

<critical_requirements>

Before writing UI code

**Reach for the semantic element before the ARIA attribute.** `<button>`, `<a href>`, `<nav>` and `<table>` arrive with a role, keyboard behaviour and focus already correct — every one of which has to be rebuilt by hand on a `<div>`, and the rebuild is where the failures are.

**Make every interactive element reachable and visibly focused.** Keyboard users navigate by what the focus ring tells them, so `outline: none` without a replacement leaves them moving blind through the page.

**Give every control a name a screen reader can announce.** An icon-only button reads as "button" without one, which tells the listener there is something there and nothing about what it does.

**Hold text to 4.5:1 against its background, and UI boundaries and focus indicators to 3:1.** Below that the text is unreadable in bright light, on a cheap panel, or to anyone with reduced contrast sensitivity — which is most people eventually.

**Pair every colour signal with a shape, an icon or a word.** Red-for-error carries nothing to a red-green colour-blind reader, and nothing at all through a screen reader.

**Announce content that appears without a page change.** A validation error, a saved confirmation and a loaded result are all silent unless they arrive in a live region.

</critical_requirements>

---

**Auto-detection:** accessibility, a11y, WCAG, ARIA, aria-label, aria-labelledby, aria-describedby, aria-live, aria-expanded, aria-invalid, role attribute, keyboard navigation, focus management, focus trap, focus-visible, skip link, landmark, screen reader, sr-only, colour contrast, prefers-reduced-motion, tabindex, axe

**Applies to:**

• Keyboard reachability, tab order, focus movement and focus indicators
• ARIA roles, states and properties, and when the element makes them unnecessary
• Contrast ratios and colour-independent information
• Accessible names, live regions and announcement timing
• Target size, motion preferences, and the WCAG 2.2 criteria that added them

**Handled elsewhere:**

• Component internals for complex widgets — a tested primitive library implements the ARIA contract below; this skill states the contract so you can check whichever one you use.
• Visual design tokens — the palette is designed elsewhere, and this skill supplies the ratio it has to clear.
• Test runner mechanics — running an audit is your test tooling's job, and what to assert is here.
• Content authoring — reading level, plain language and caption text are writing decisions rather than markup ones.

---

<philosophy>

Philosophy

An accessible interface is not a variant of the interface. It is the same one, built out of elements that already carry meaning, with the parts a browser cannot infer stated explicitly.

That reframes most of the work as subtraction. Semantic HTML is the accessible baseline; every `<div>` that replaces a real element is a debt paid back in ARIA attributes, key handlers and focus management, and paid back badly. The attributes below exist for the cases where no element carries the meaning — not as a layer applied over markup that could have carried it.

Build for the keyboard first. Everything a pointer can do, a keyboard has to do too, and a design that works without a mouse works with one.

</philosophy>

---

<decision_framework>

Which mechanism the case needs

What is being built?
├─ Something that acts when activated → <button>
│   └─ Icon only → add an accessible name
├─ Something that navigates → <a href>
│   └─ Current destination → aria-current="page"
├─ A structural region → <nav>, <main>, <header>, <aside>, <footer>
│   └─ More than one of a kind → label each with aria-label
├─ A complex widget — dialog, listbox, tabs, combobox, tree
│   └─ Take a tested primitive. The ARIA contract is large,
│      and a partial implementation reads as broken rather than absent.
└─ Content that appears without navigation
    ├─ An error or something urgent → role="alert"
    └─ Progress or confirmation → role="status"

**ARIA or not:** the first rule of ARIA is not to use ARIA. `role="button"` on a `<div>` gives a screen reader the right word and gives the keyboard nothing, so the handlers, `tabindex` and focus styling are all still owed. Reach for ARIA when no element expresses the thing — a live region, a disclosure's `aria-expanded`, a sort direction on a column header.

**AA or AAA:** AA is the compliance target and what regulat