Accessibility Standards

---
name: mav-bp-accessibility
description: Accessibility conventions for projects with user-facing interfaces. Covers WCAG 2.1 AA compliance, semantic HTML, keyboard navigation, colour contrast, screen reader support, and automated a11y testing. Applied when building or reviewing user-facing web or mobile applications.
user-invocable: false
disable-model-invocation: true
---

# Accessibility Standards

Ensure user-facing interfaces are usable by everyone, including people who rely on assistive technology.

## Maverick's Rules

- **WCAG 2.2 AA is the baseline, not the ceiling** — all user-facing interfaces must meet it.
- **Scope**: web and mobile UIs only. Does NOT apply to CLIs, REST/GraphQL APIs, backend services, batch jobs/workers/daemons, or internal build tools. If the project has no user-facing interface, skip this skill entirely.
- **Semantic HTML first** — native elements before ARIA. No ARIA is better than bad ARIA; never override native semantics; any custom ARIA widget must implement its full keyboard interaction pattern.
- **Automated accessibility testing must run in CI** (axe-core, Lighthouse CI, pa11y, eslint-plugin-jsx-a11y — whatever fits the stack). Automated tools catch only ~30% of issues; they are necessary but not sufficient.
- **Manual verification is required** for what automation misses: keyboard-only operation of the whole page (Tab/Shift+Tab/Enter/Space/Escape/arrows, no traps outside modals), screen reader announcement of labels, errors, and dynamic content, and focus management in modals and SPA route changes (trap in dialog, restore to trigger on close).
- **Zoom and reflow**: content usable at 200% zoom; no horizontal scrolling at 320px viewport width.
- **Auto-playing media is prohibited** — playback must be user-initiated.
- **Focus indicators**: never `outline: none` without a `:focus-visible` replacement; indicators need at least 3:1 contrast against the surrounding background.
- **Never use colour alone** to convey state — pair it with text, an icon, or a pattern.

## Project Implementation Lookup

Check for `docs/maverick/skills/accessibility/SKILL.md`. If present, read it and follow it — it wins on specifics (library, config, conventions). If missing, proceed with these standards and note the gap in your summary.

## Detecting Accessibility Issues in Code Review

When reviewing code for user-facing interfaces, flag these patterns:

| Pattern | Issue | Fix |
| ------- | ----- | --- |
| `<div onclick="...">` | Non-semantic interactive element | Use `<button>` or `<a>` |
| `outline: none` without replacement | Invisible focus indicator | Add `focus-visible` style |
| `<img>` without `alt` attribute | Missing text alternative | Add descriptive `alt` or `alt=""` for decorative |
| `<input>` without associated `<label>` | Unlabelled form field | Add `<label for="...">` |
| Colour alone indicates state | Inaccessible to colour-blind users | Add icon, text, or pattern |
| `tabindex` value > 0 | Breaks natural tab order | Use `tabindex="0"` or `-1` only |
| `aria-hidden="true"` on focusable element | Hidden but still keyboard-reachable | Remove from tab order or remove `aria-hidden` |
| Auto-playing video or audio | Disruptive, not user-initiated | Require explicit play action |
| Placeholder used as label | Label disappears on input, poor contrast | Add a visible `<label>` |
| Missing `lang` attribute on `<html>` | Screen reader uses wrong language | Add `<html lang="en">` (or appropriate language) |
| Custom widget without keyboard handling | Inoperable for keyboard users | Implement full keyboard interaction pattern |
| Error shown only by colour change | Screen readers cannot detect colour | Add text message and `aria-describedby` |

<!-- maverick-plugin-version: 5.1.1 -->