Loading...
Loading...
Use this skill when the user needs to make their app accessible, comply with WCAG guidelines, implement ARIA patterns, support screen readers, or ensure keyboard navigation works. Covers WCAG 2.2, semantic HTML, assistive technology testing, and inclusive design.
npx skill4agent add whawkinsiv/claude-code-skills accessibility| You Decide | Claude Code Implements |
|---|---|
| "Our app must be keyboard-navigable" | Proper focus management, tab order, keyboard handlers |
| "All images need descriptions" | Alt text on every image |
| "Forms must have clear error messages" | Linked labels, aria-describedby, validation messages |
| "We support screen readers" | Semantic HTML, ARIA roles, live regions |
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 modalsEnsure 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| Element | Minimum Contrast Ratio |
|---|---|
| Body text | 4.5:1 against background |
| Large text (18px+ or 14px+ bold) | 3:1 |
| UI components (borders, icons) | 3:1 |
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 checkerFix 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-describedbyImprove 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)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 usersRun 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| Mistake | Fix |
|---|---|
Adding | Never remove focus indicators. Style them instead. |
Using | Use semantic HTML elements. Buttons are |
| Placeholder as label | Always use a visible |
| Ignoring keyboard users | Test without a mouse. If you can't complete the flow, keyboard users can't either. |
| Bolting on ARIA to fix bad HTML | Fix the HTML first. ARIA is a repair tool, not a substitute. |
| Waiting until "later" to care | Build semantic HTML from day one. It's free and prevents 80% of issues. |