Frontend Accessibility By Construction
Accessibility retrofitted after a component ships is ARIA-as-plaster: attributes
bolted onto a <div> that was never operable to begin with. This skill is about
the order of operations — semantic structure and keyboard operability are
decided before a line of markup is written, not audited in afterward.
Composes with the library:
- non-overwhelming-ux — cognitive/sensory load (chunking, pacing, interruption control) is that skill's scope; this skill governs perceivability and operability of a single component
- resilient-ui-states — error/loading/empty states must also be accessible (announced, not just visible); see that skill for the state machine itself
- validate-at-the-boundary — this skill covers the accessible surfacing of a validation error (aria-invalid, aria-describedby); that skill covers the validation logic itself
Standards (primary source: normative)
Source: WCAG 2.2, W3C Recommendation, WAI Quick Reference.
| Rule | Level | Applies when | Does not apply when |
|---|---|---|---|
| MUST — every interactive element reachable and operable via keyboard alone, no trap | A (2.1.1, 2.1.2) | Any custom widget (dropdown, tabs, modal, carousel) | Never waived — this is the floor |
| MUST — visible focus indicator on every focusable element | AA (2.4.7) | Always, unless a component-specific indicator (e.g. selected-state styling) is equally visible | Do not remove outline without a replacement that meets the same contrast |
| MUST — semantic structure conveys relationships (headings, lists, form labels) programmatically, not by layout alone | A (1.3.1) | Any content where visual grouping implies semantic grouping | N/A |
| MUST — target size ≥24×24 CSS px, or equivalent spacing, for pointer/touch targets | AA (2.5.8) | Buttons, links, form controls in normal reading flow | Inline text links, elements with an unstyled default browser rendering with no alternative |
| MUST — any drag interaction has a non-drag alternative (single pointer, no path) | AA (2.5.7) | Reordering lists, sliders, drag-to-dismiss | Drag is essential and no equivalent exists (rare — justify explicitly) |
| SHOULD — no more than one unexpected context change on input alone (focus, autosubmit) | AA (3.2.2) | Form fields, selects | User was warned beforehand |
MUST = the interface is broken without it. SHOULD = strong default; a documented exception with a stated reason is acceptable. MAY = situational judgment call, no standard mandates it.
The precedence rule (methodological decision, not a standard)
- Native HTML element first.
<button>,<a href>,<select>,<input>,<dialog>already carry keyboard behavior, focus management, and semantics for free. Reaching for a<div onClick>is opting out of all of it. - ARIA only where native HTML has no equivalent (a combobox, a tree, a tablist). Follow the ARIA Authoring Practices Guide patterns exactly — a custom ARIA pattern invented ad hoc is worse than no ARIA, because it claims a contract with assistive tech it doesn't fulfill.
- Never use ARIA to fix a semantic problem native HTML would have
prevented.
role="button"on a<div>still needstabindex,onKeyDownfor Enter/Space, and focus styling manually reimplemented — every one of which is a place to regress silently on the next edit.
Failure modes / anti-patterns
- Div-button:
<div onClick>with norole,tabindex, or keyboard handler — invisible to keyboard and screen reader users, works fine in a manual mouse-only test, which is why it ships. - Focus black hole: opening a modal/menu that doesn't move focus into it, or closing one that doesn't return focus to the trigger — keyboard users land nowhere or lose their place.
- Outline: none with no visible replacement — passes a visual design review, fails every keyboard-only walkthrough.
- ARIA overload: adding
role,aria-label, andaria-*to an element that already had correct native semantics — redundant announcements are as harmful as missing ones. - Icon-only control with no accessible name — a trash-can icon button with
no
aria-label/visually-hidden text announces as "button" with no purpose. - Live region misuse: wrapping static content in
aria-live"just in case" — announces on every re-render, including irrelevant ones.
Verifiable checks (for audit, human or agent)
- Every interactive element is reachable via Tab, in a logical order, with no keyboard trap (test: unplug the mouse, complete the flow).
- Every focused element has a visible indicator distinguishable from unfocused state.
- Every
<img>conveying information hasalt; every purely decorative image hasalt=""or is a CSS background. - Every form input has a programmatically associated
<label>(not placeholder-only). - Every icon-only interactive control has an accessible name
(
aria-label,aria-labelledby, or visually-hidden text). - Opening a modal/dialog moves focus inside it; closing it returns focus to the trigger; Escape closes it.
- Tap targets measure ≥24×24px or have equivalent effective spacing.
- Any drag interaction has a keyboard/click alternative.
- Run an automated check (axe-core, Lighthouse a11y) as a floor, not a ceiling. Estimates of automated coverage vary by what's being counted and by vendor — WebAIM Million 2026-adjacent reporting puts machine-detectable success criteria around 20-30%, while Deque cites axe-core catching "on average 57%" of issues by volume (a few highly automatable failure types, like missing alt text and low contrast, dominate raw counts). No single number is authoritative across sources — treat automated tooling as necessary and clearly insufficient, and follow it with keyboard-only and screen-reader spot checks regardless of which estimate you use.
What this skill does not cover
Color contrast as a pure aesthetic choice is out of scope except where it crosses the WCAG 1.4.3 threshold (4.5:1 normal text, 3:1 large text/UI components) — that threshold is a comprehension/perceivability requirement, not a design preference, and is the one visual rule this skill enforces.