A11y Checklist

Accessibility checklist (WCAG 2.2 AA)

Use this as a walk-through, top to bottom. If you can't answer "yes" or "N/A" for a line, fix it.

Semantics

• [ ] The element matches the intent. ` for actions. for navigation. Lists use /. Landmarks use ////`.
• [ ] Headings form a valid outline — one ``, no skipped levels.
• [ ] Forms have `s (or aria-labelledby`). Placeholder is not a label.

Keyboard

• [ ] Every interactive element is reachable by Tab.
• [ ] Focus order matches visual order.
• [ ] No focus traps. Modals trap focus only while open and restore on close.
• [ ] Focus is visible (outline, ring, or theme equivalent). Don't remove :focus-visible without replacement.
• [ ] Keyboard shortcuts don't collide with screen-reader virtual cursor.

Names & descriptions

• [ ] Every interactive control has an accessible name. Icon-only buttons: aria-label.
• [ ] Images: meaningful alt; decorative alt="".
• [ ] Form errors are programmatically associated via aria-describedby.

States

• [ ] aria-expanded, aria-selected, aria-pressed, aria-checked, aria-invalid reflect the current state and update as it changes.
• [ ] Loading states have aria-busy or a live region announcement.
• [ ] Async status changes are announced in a role="status" or role="alert" live region (use alert sparingly — it's interruptive).

Contrast

• [ ] Normal text ≥ 4.5:1 vs background.
• [ ] Large text (≥ 18pt or 14pt bold) ≥ 3:1.
• [ ] UI components (form borders, focus rings, icon glyphs) ≥ 3:1.
• [ ] Don't rely on color alone to convey meaning — error state must have an icon or text too.

Motion

• [ ] Respect prefers-reduced-motion. No auto-animating carousels, parallax, or transitions without the opt-out.
• [ ] Videos under 5s ok; longer needs pause/stop controls.
• [ ] No flashing over 3 times per second in any region larger than ~25% of the viewport.

Structure & navigation

• [ ] Page has a ` landmark and a sensible lang on `.
• [ ] Skip-to-content link at the top (or equivalent landmark structure).
• [ ] Page title is descriptive and unique per route.

Errors & status

• [ ] Inline errors say what was wrong and how to fix ("Email must include an @").
• [ ] Errors appear near the input, are announced to AT, and don't rely solely on color.
• [ ] Required fields are marked both visually and programmatically (aria-required or required).

Testing

• [ ] Keyboard-only pass: unplug the mouse, try the flow.
• [ ] Screen-reader pass (VoiceOver / NVDA) on critical flows.
• [ ] axe or similar linter in CI — treat findings as bugs, not noise.

Smells

• role="button" on a ` — use ` instead
• aria-hidden on interactive content — almost always wrong
• Tabindex > 0 — almost always wrong
• "Click here" link text — unhelpful out of context

Success criteria quick map

Common SCs you'll cite: 1.1.1 (non-text alt), 1.3.1 (info and relationships), 1.4.3 (contrast), 2.1.1 (keyboard), 2.4.3 (focus order), 2.4.7 (focus visible), 3.3.1 (error identification), 4.1.2 (name, role, value), 4.1.3 (status messages).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: atuljha23
• Source: atuljha23/holocron
• License: MIT
• Homepage: https://atuljha23.github.io/holocron/

Install and usage instructions live in the source repository linked above.