Accessibility Audit

Accessibility Audit

Overview

Accessibility is not an afterthought — it's a legal requirement and an ethical obligation. 15% of the world's population has a disability. Accessible design is better design for everyone.

Core principle: If it doesn't work with a keyboard and a screen reader, it's broken for millions of users.

The Iron Law

NO INTERACTIVE ELEMENT WITHOUT KEYBOARD ACCESS. NO IMAGE WITHOUT ALT TEXT. NO FORM INPUT WITHOUT LABEL. NO COLOR AS SOLE INDICATOR.

When to Use

• Building any user interface
• Auditing existing UI for compliance
• Before launch or major release
• When accessibility complaints arise
• During frontend audit
• When targeting government or enterprise clients (legal compliance)

When NOT to Use

• CLI tools or backend services (no UI)
• API-only projects (use api-design-audit)
• If the frontend-audit quick accessibility check found no issues AND the app is simple ( | ` | Screen readers announce "navigation" |

| Button | ` | or | Focusable, Enter/Space activated, announced as "button" | | Heading | → hierarchy | | Screen readers build page outline from headings | | List | / | with bullets | Screen readers announce "list, 5 items" | | Form | with | with placeholder only | Labels persist, associate with inputs | | Link | | | Focusable, announced as "link" | | Main content | | | Skip navigation target, landmark | | Table | with | grid with CSS | Screen readers announce headers per cell | | Section | | ` | Landmark navigation |

Detection:

# Find div-as-button anti-pattern
grep -rn "div.*onClick\|span.*onClick" --include="*.tsx" --include="*.jsx" . | grep -v node_modules

# Find missing labels
grep -rn "` not `` |
| Don't change native semantics | Don't put `role="heading"` on a `` |
| All interactive elements must be keyboard accessible | `tabindex="0"` + keydown handlers |
| Don't use `role="presentation"` on focusable elements | It strips semantics but element remains interactive |
| All form elements need accessible names | `aria-label`, `aria-labelledby`, or `` |

### Phase 7: Responsive and Zoom

1. DOES the page work at 200% browser zoom? (WCAG requirement)
2. IS there horizontal scrolling at 320px viewport width?
3. DO touch targets meet minimum size? (44x44px on mobile)
4. IS text resizable without breaking layout?
5. ARE there text-only zoom issues? (content overflow, overlap)

## Testing Tools

| Tool | Checks | Phase |
|------|--------|-------|
| axe DevTools (browser extension) | Automated WCAG checks | All |
| Lighthouse Accessibility | Accessibility score (0-100) | Quick scan |
| WAVE | Visual accessibility report | All |
| NVDA (Windows) / VoiceOver (Mac) | Screen reader testing | Phase 1, 2 |
| Keyboard only (Tab + Enter + Escape) | Keyboard navigation | Phase 1 |
| WebAIM Contrast Checker | Color ratio verification | Phase 4 |
| prefers-reduced-motion test | Animation respect | Phase 3 |
| Chrome DevTools Rendering | Color blindness simulation | Phase 4 |

## Output Format

```markdown
# Accessibility Audit: [Project Name]

## WCAG 2.1 Compliance
- **Target:** AA
- **Current:** [AA / Partial AA / Non-compliant]
- **Automated Score:** [Lighthouse accessibility score] / 100

## Findings by Category
| Category | Issues | Critical | Assessment |
|----------|--------|----------|------------|
| Keyboard Navigation | N | N | 🔴/🟡/🟢 |
| Semantic HTML | N | N | 🔴/🟡/🟢 |
| Images & Media | N | N | 🔴/🟡/🟢 |
| Color & Contrast | N | N | 🔴/🟡/🟢 |
| Forms | N | N | 🔴/🟡/🟢 |
| ARIA Usage | N | N | 🔴/🟡/🟢 |
| Responsive/Zoom | N | N | 🔴/🟡/🟢 |

## Detailed Findings
[Standard severity format]

## Verdict: [PASS / CONDITIONAL PASS / FAIL]

Red Flags — STOP and Investigate

• outline: none without replacement focus style
• Click handlers on ` or (not `)
• No alt text on any images
• Color as the only indicator of state (error, success, required)
• Modals that don't trap focus
• No skip navigation link
• Heading hierarchy violations (h1 → h3, skipping h2)
• Form inputs without associated labels
• Auto-playing audio or video without controls
• Text that can't be resized
• No prefers-reduced-motion handling for animations

Integration

• Part of: frontend-audit includes quick accessibility check
• Deep dive: This skill for full WCAG compliance audit
• During build: code-review checks accessibility basics
• Legal: Required before launch for government/enterprise clients

Source & license

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

• Author: boparaiamrit
• Source: boparaiamrit/skills-by-amrit
• License: MIT

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