Accessibility (a11y)

Accessibility is not optional — it’s a quality attribute like performance or security. The good news: if you build with correct HTML from the start, you get 80% of accessibility for free. This skill tells you what to prioritize and what to hand to Claude Code.

What You Decide vs. What AI Implements

Rule: You set the standard. Claude Code does the implementation. Your job is to test it.

Priority Order (What Gives You the Most Value)

Don’t try to achieve WCAG AAA compliance on day one. Start with the highest-impact wins:

Tier 1: Start Here (Covers 80% of Issues)

1. Semantic HTML — The foundation of all accessibility
2. Keyboard navigation — Every interactive element works without a mouse
3. Color contrast — Text is readable against its background
4. Form labels — Every input has a visible, linked label
5. Image alt text — Every meaningful image has a description

Tier 2: Add Next (After Launch)

6. Focus management — Modals trap focus, focus returns on close
7. Error messages — Connected to inputs, announced by screen readers
8. Skip navigation — Link to skip to main content
9. Reduced motion — Respect user’s motion preferences

Tier 3: Polish (After Product-Market Fit)

10. Full ARIA patterns — Custom components (tabs, menus, date pickers)
11. Screen reader testing — Test full flows with VoiceOver/NVDA
12. Color blindness — Don’t rely on color alone to convey information

Tier 1: Implementation

Semantic HTML

Tell AI:

Audit and fix HTML semantics across the app:
- Use <button> for actions, <a> for navigation (never the reverse)
- Use <nav>, <main>, <aside>, <header>, <footer>, <article>, <section> for page structure
- Use <h1>-<h6> in order (no skipped levels, never used just for styling)
- Use <label> linked to every form input
- Use <ul>/<ol> for lists
- Use <table> with proper <th> headers for tabular data
- Use <dialog> for modals

Keyboard Navigation

Tell AI:

Ensure full keyboard accessibility:
- Every interactive element (button, link, input, select) must be reachable with Tab
- Every interactive element must be activatable with Enter or Space
- Tab order must follow visual reading order
- Focus states must be clearly visible (not just outline: none)
- Modals must trap focus inside and return focus to the trigger on close
- Add a "Skip to main content" link as the first focusable element

Color Contrast

Tell AI:

Check and fix color contrast across the app:
- Verify all text meets WCAG AA contrast ratios (4.5:1 for body, 3:1 for large text)
- Verify UI elements (borders, icons, focus rings) meet 3:1 contrast
- Don't rely on color alone — add icons, patterns, or text labels alongside color indicators
- Test with the browser's built-in contrast checker

Form Labels and Alt Text

Tell AI:

Fix form accessibility:
- Every input must have a visible <label> linked via for="id" attribute
- Placeholder text is NOT a label (it disappears on focus)
- Required fields: add visual indicator AND aria-required="true"
- Add autocomplete attributes for personal data: autocomplete="email", "name", etc.

Fix image accessibility:
- Every meaningful image needs descriptive alt text (max 125 chars)
- Decorative images need alt="" (empty alt, not missing alt)
- Charts and diagrams need a text description nearby or via aria-describedby

Tier 2: After Launch

Focus Management and Error Messages

Tell AI:

Improve focus management and error handling:
- When a modal opens, move focus to the first interactive element inside
- When a modal closes, return focus to the button that opened it
- Trap focus inside modals (Tab shouldn't escape to the background)
- Connect error messages to inputs via aria-describedby
- When a form has errors, add aria-invalid="true" to invalid fields
- Announce dynamic content changes with aria-live="polite" (status messages) or aria-live="assertive" (errors)

Reduced Motion

Tell AI:

Respect user motion preferences:
- Add a CSS media query: @media (prefers-reduced-motion: reduce) { * { animation: none !important; } }
- Disable autoplay on videos and carousels when reduced motion is preferred
- Keep transitions under 200ms or remove them for reduced-motion users

Testing Checklist

Run through these checks before each release:

Quick Test (5 minutes)

• Put your mouse away. Navigate the entire signup → core action flow with keyboard only.
• Can you reach every button, link, and input with Tab?
• Can you see where focus is on every element?
• Can you activate every button with Enter or Space?
• Can you escape every modal with Escape?

Automated Test

Tell AI:

Run an accessibility audit:
- Run axe-core or Lighthouse accessibility audit on our main pages
- Report all violations grouped by severity (critical, serious, moderate, minor)
- Fix all critical and serious violations
- Add accessibility checks to our CI pipeline so new issues are caught automatically

Deeper Test (When Ready)

• Test with VoiceOver (Mac: Cmd+F5) or NVDA (Windows, free)
• Test at 200% browser zoom — no content loss or horizontal scrolling
• Test with a color blindness simulator browser extension
• Verify all videos have captions

Common Mistakes