Accessibility (a11y)
Trigger phrases: "a11y", "accessibility", "WCAG", "screen reader", "keyboard navigation", "contrast", "ARIA", "keyboard only", "with a keyboard", "keyboard focus", "without a mouse", "focus ring", "tab order", "alt text", "color blind", "colour blind", "voiceover", "talkback", "reduced motion"
Goal: make the interface usable by everyone, including keyboard, screen reader, and low vision. Baseline target: WCAG 2.1 AA.
Stack-agnostic (web/React/RN); do a web search when needed for framework-specific APIs.
Checklist
How
- Start with semantics — the right element solves 80%. Use
button instead of role="button"+div.
- Navigate with the keyboard — drop the mouse, run the whole flow with Tab/Shift-Tab/Enter/Escape; is focus visible and its order sensible.
- Naming — does every interactive element have an accessible name (
aria-label on visual-only icon buttons).
- Contrast — check color pairs against the ratio; don't convey meaning by color alone (add an icon/text).
- Dynamic content — notify the screen reader via a live region (
aria-live); manage modal focus.
- Automated + manual — tools like linters/axe are the baseline; but manual keyboard+reader testing is essential (tools don't catch 100%).
React / RN note
- Web React: semantic element in JSX +
htmlFor/aria-*; use button instead of a clickable div.
- React Native:
accessible, accessibilityLabel, accessibilityRole, accessibilityState (coordinate with frontend-rn-expo).
- Flutter: the guideline test (
meetsGuideline with the tap-target, label and contrast guidelines) on every new screen (coordinate with frontend-flutter).
Invariant rules
- Semantics first, ARIA second — wrong ARIA does harm.
- Must be fully usable by keyboard — without a mouse.
- Color cannot be the sole carrier of meaning.
- Automated tools are not enough — manual keyboard+reader testing.
- Follow the existing design system — if there is a component library, keep its accessible pattern.
1---2name: a11y-33description: |4 Frontend accessibility audit (WCAG): semantic HTML, keyboard access, focus management, contrast, ARIA, screen readers.5 Use when building or changing UI, or before shipping a user-facing screen.6metadata:7 source: https://skillmd.com/skills/byerlikaya/a11y-38---910# Accessibility (a11y)1112<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->13Trigger phrases: "a11y", "accessibility", "WCAG", "screen reader", "keyboard navigation", "contrast", "ARIA", "keyboard only", "with a keyboard", "keyboard focus", "without a mouse", "focus ring", "tab order", "alt text", "color blind", "colour blind", "voiceover", "talkback", "reduced motion"1415Goal: make the interface usable by **everyone**, including keyboard, screen reader, and low vision. Baseline target: **WCAG 2.1 AA**.16Stack-agnostic (web/React/RN); do a web search when needed for framework-specific APIs.1718## Checklist19- [ ] **Semantic HTML**: `button`/`a`/`nav`/`main`/`h1..h6` correct; no `div`-buttons20- [ ] **Keyboard**: every interaction reachable via Tab, sensible order, visible **focus ring**21- [ ] **Focus management**: focus moves on modal/route change, focus trap correct22- [ ] **Contrast**: text ≥ 4.5:1, large text ≥ 3:123- [ ] **Alt text**: `alt` on meaningful images; `alt=""` on decorative images24- [ ] **Forms**: every input has a `label`; error message programmatically linked (`aria-describedby`)25- [ ] **ARIA**: only when needed; wrong ARIA is worse than no ARIA; role/name/state correct26- [ ] **Motion/animation**: respect `prefers-reduced-motion`27- [ ] **Language**: `<html lang>` correct (coordinate with i18n)2829## How301. **Start with semantics** — the right element solves 80%. Use `button` instead of `role="button"`+`div`.312. **Navigate with the keyboard** — drop the mouse, run the whole flow with Tab/Shift-Tab/Enter/Escape; is focus visible and its order sensible.323. **Naming** — does every interactive element have an accessible name (`aria-label` on visual-only icon buttons).334. **Contrast** — check color pairs against the ratio; don't convey meaning by color alone (add an icon/text).345. **Dynamic content** — notify the screen reader via a live region (`aria-live`); manage modal focus.356. **Automated + manual** — tools like linters/axe are the baseline; but manual keyboard+reader testing is essential (tools don't catch 100%).3637## React / RN note38- Web React: semantic element in JSX + `htmlFor`/`aria-*`; use `button` instead of a clickable `div`.39- React Native: `accessible`, `accessibilityLabel`, `accessibilityRole`, `accessibilityState` (coordinate with `frontend-rn-expo`).40- Flutter: the guideline test (`meetsGuideline` with the tap-target, label and contrast guidelines) on every new screen (coordinate with `frontend-flutter`).4142## Invariant rules431. **Semantics first, ARIA second** — wrong ARIA does harm.442. Must be **fully usable by keyboard** — without a mouse.453. **Color cannot be the sole carrier of meaning.**464. **Automated tools are not enough** — manual keyboard+reader testing.475. **Follow the existing design system** — if there is a component library, keep its accessible pattern.