Accessibility Audit

Accessibility Audit (WCAG 2.2 + a11y)

This skill audits a project for accessibility issues and fixes them. Based on:

• WCAG 2.2 (Level A + AA): https://www.w3.org/TR/WCAG22/
• The A11Y Project checklist: https://www.a11yproject.com/checklist/

Invoke this skill when an accessibility audit is requested. It should scan the project automatically without assuming a specific slash-command system.

Agent Portability

This skill must work across Codex, Claude, and other SKILL.md-compatible agents. Do not assume slash commands, Claude-only memory files, or a specific package manager. Use the repository's existing tools and conventions. If no automated accessibility tooling is installed, perform the manual audit and recommend optional external tools without installing dependencies.

Step 0: Scan the project

Read the project's index.html, all page components, layout components, and form components. Build a mental map of:

• Which pages exist
• Which components handle user interaction (forms, buttons, links, modals, accordions)
• Which components have animations or media (video, audio)
• What CSS framework is used (Tailwind, vanilla, etc.)
• Whether prefers-reduced-motion is already handled

Step 1: Audit — check every category

Go through each category below. For every issue found, note the file, line, and which WCAG criterion it violates. Group findings by severity (Critical → Major → Minor).

1. Global Code

2. Headings

3. Images & Icons

4. Color Contrast

5. Keyboard & Focus

6. Forms

7. Links & Buttons

8. Media & Animation

9. Mobile & Touch

10. ARIA & Semantics

11. WCAG 2.2 New Criteria

Step 2: Report findings

Present findings as a table grouped by severity:

## Accessibility Audit Results

### 🔴 Critical (breaks access for some users)
| Issue | File | WCAG | Fix |
|-------|------|------|-----|
| ... | ... | ... | ... |

### 🟠 Major (significant barrier)
| Issue | File | WCAG | Fix |
|-------|------|------|-----|
| ... | ... | ... | ... |

### 🟡 Minor (improvement opportunity)
| Issue | File | WCAG | Fix |
|-------|------|------|-----|
| ... | ... | ... | ... |

### ✅ Passing
- [list what's already good]

Ask the user: "Should I fix the issues automatically? All issues or only selected ones?"

Step 3: Fix issues

Apply fixes directly in the codebase. For each fix:

• Edit the file
• Add a brief comment only if the fix isn't self-explanatory
• Never break existing functionality

Common fixes:

Missing alt text:

// Decorative → alt=""
<img src="..." alt="" />

// Meaningful → descriptive alt
<img src="..." alt="Description of image content" />

Missing labels:

<label htmlFor="email">E-Mail</label>
<input id="email" type="email" aria-required="true" />

// Or for icon-only buttons:
<button aria-label="Open menu">
  <MenuIcon aria-hidden="true" />
</button>

Focus styles:

:focus-visible {
  outline: 2px solid var(--c-accent);
  outline-offset: 2px;
}

Skip link:

<a href="#main-content" className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-white focus:text-black">
  Skip to content
</a>

prefers-reduced-motion:

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

External links:

<a href="..." target="_blank" rel="noopener noreferrer">
  Link Text <span className="sr-only">(opens in new tab)</span>
</a>

aria-live for dynamic content:

<div aria-live="polite" aria-atomic="true">
  {statusMessage}
</div>

Step 4: Summary

After fixing, present:

Accessibility Audit Complete!

✅ [N] issues fixed
⚠️ [N] issues need manual testing (keyboard nav, screen reader)
📊 WCAG 2.2 Level AA compliance: [estimated %]

Fixed:
- [list of fixes applied]

Manual testing recommended:
- Tab through all pages — verify focus order and visibility
- Test with screen reader (VoiceOver: Cmd+F5 on Mac)
- Test at 200% zoom — verify no content is cut off
- Test at 320px width — verify no horizontal scroll
- Test with prefers-reduced-motion enabled

Tools for further testing:
- axe DevTools: browser extension for automated checks
- WAVE: https://wave.webaim.org/
- Lighthouse Accessibility audit in Chrome DevTools

Rules

• Target WCAG 2.2 Level AA (not AAA, unless already implemented)
• prefers-reduced-motion handling is mandatory, not optional
• Never remove existing accessibility features
• Use English for sr-only text in examples; localize to the project's language at implementation time
• Follow the project's existing code style and framework conventions
• Do NOT install any npm packages — use native HTML/ARIA
• Automated tools catch ~30% of issues — this audit is the manual review layer
• Always recommend manual testing with keyboard + screen reader after fixes