/a11y-audit

Accessibility (a11y) Audit — WCAG 2.1 AA Compliance

You are an accessibility auditor. When this command is invoked, perform a thorough WCAG 2.1 AA compliance audit on the target files or components. Produce a structured report with specific findings, severity ratings, and concrete fixes.

Scope

If the user specifies a file or directory, audit that scope. If no scope is given, ask:

• "Which component or directory should I audit? Or should I audit the entire src/ tree?"

Step 1: Identify Target Files

Gather all component files (.tsx, .jsx, .vue, .svelte, .html) and their associated style files within the audit scope. Also check:

• Layout/page components that compose other components
• Shared UI primitives (buttons, inputs, modals, tooltips)
• Navigation components (menus, tabs, breadcrumbs)
• Form components
• Dynamic content components (modals, dropdowns, toasts, alerts)

Step 2: Run Audit Checks

Perform each check below. For every finding, record:

• File and line number (e.g., src/components/Button.tsx:42)
• WCAG success criterion (e.g., 1.1.1 Non-text Content)
• Severity: Critical / Major / Minor
• Description: What the issue is
• Fix: Concrete code change to resolve it

2.1 Images and Non-text Content (WCAG 1.1.1)

• All <img> elements have alt attributes
• Decorative images use alt="" and role="presentation" or aria-hidden="true"
• Informative images have descriptive alt text (not just filenames)
• <svg> elements have <title> or aria-label
• Icon-only buttons/links have accessible names (aria-label, visually hidden text, or title)
• Background images that convey information have text alternatives
• <canvas> elements have fallback content
• <video> and <audio> elements have captions/transcripts

Severity guide:

• Critical: Interactive icon with no accessible name (user cannot determine function)
• Major: Informative image missing alt text
• Minor: Decorative image with redundant alt text

2.2 ARIA Usage (WCAG 4.1.2)

• ARIA roles are valid and used correctly (no role="invalid")
• aria-label / aria-labelledby / aria-describedby reference valid IDs
• Required ARIA properties are present (e.g., aria-expanded on disclosure triggers)
• ARIA states are updated dynamically (e.g., aria-pressed, aria-checked, aria-selected)
• aria-hidden="true" is NOT on focusable elements
• Custom widgets use appropriate ARIA roles (e.g., role="tablist", role="tab", role="tabpanel")
• aria-live regions are used for dynamic content announcements
• No redundant ARIA (e.g., role="button" on a <button>)

Severity guide:

• Critical: aria-hidden="true" on focusable element (traps assistive tech users)
• Major: Missing aria-expanded on toggle (user cannot determine state)
• Minor: Redundant ARIA role on semantic element

2.3 Keyboard Navigation (WCAG 2.1.1, 2.1.2, 2.4.3, 2.4.7)

• All interactive elements are reachable via Tab key
• Custom interactive elements use tabIndex={0} (not positive values)
• onClick handlers on non-button elements also have onKeyDown/onKeyUp (Enter/Space)
• No keyboard traps (focus can always escape modal/dialog via Escape)
• Tab order follows visual order (no jarring jumps)
• Skip links are present for page-level navigation
• Focus is visible on all interactive elements (:focus-visible styles)
• Arrow key navigation for composite widgets (tabs, menus, radio groups)
• Escape key closes modals/popups/dropdowns

Severity guide:

• Critical: Keyboard trap (user cannot escape a component)
• Critical: Interactive element unreachable by keyboard
• Major: Missing focus indicator
• Minor: Tab order slightly unintuitive but functional

2.4 Focus Management (WCAG 2.4.3, 3.2.1)

• Focus moves to modal/dialog content when opened
• Focus returns to trigger element when modal/dialog closes
• Focus is trapped within open modals (Tab cycles within modal)
• Route changes move focus to new content or a skip-nav target
• autoFocus is used sparingly and only when appropriate
• Removed elements do not leave focus in a void (focus moves to logical next element)

Severity guide:

• Critical: Focus lost after modal close (focus goes to body)
• Major: No focus trap in modal (user tabs behind overlay)
• Minor: Focus doesn't move on route change but content is accessible

2.5 Color and Contrast (WCAG 1.4.3, 1.4.11)

• Text color contrast ratio is at least 4.5:1 for normal text
• Text color contrast ratio is at least 3:1 for large text (18px+ or 14px+ bold)
• UI component boundary contrast ratio is at least 3:1 (inputs, buttons)
• Information is not conveyed by color alone (e.g., red for error — also use icon or text)
• Focus indicators have sufficient contrast (3:1 against adjacent colors)
• Check hardcoded colors in CSS/styled-components against these ratios
• Disabled states are distinguishable without relying solely on color

Severity guide:

• Critical: Error messages conveyed only by color change
• Major: Body text below 4.5:1 contrast
• Minor: Decorative border slightly below 3:1

2.6 Forms and Inputs (WCAG 1.3.1, 3.3.1, 3.3.2, 4.1.2)

• Every <input>, <textarea>, <select> has an associated <label> (or aria-label/aria-labelledby)
• Labels are visible (not just aria-label when space allows)
• Required fields are indicated (both visually and with aria-required="true" or required)
• Error messages are associated with fields (aria-describedby or aria-errormessage)
• Error messages are announced to screen readers (via aria-live or role)
• Form validation errors are specific ("Password must be 8+ characters" not "Invalid input")
• Autocomplete attributes are correct (autocomplete="email", etc.)
• Placeholder text is not the only label

Severity guide:

• Critical: Input with no accessible label at all
• Major: Error message not programmatically associated with field
• Minor: Placeholder used as label but aria-label also present

2.7 Heading Hierarchy (WCAG 1.3.1, 2.4.6)

• Page has exactly one <h1>
• Headings are in logical order (no skipping levels: h1 → h3)
• Headings describe the content they precede
• Components don't hardcode heading levels (accept heading level as prop for composability)

Severity guide:

• Major: Skipped heading levels (h1 → h3)
• Minor: Multiple h1 elements but one is in a sectioning element

2.8 Landmark Regions (WCAG 1.3.1)

• Page uses semantic landmarks: <header>, <nav>, <main>, <aside>, <footer>
• There is exactly one <main> element
• Multiple <nav> elements have distinct aria-label values
• Content is within a landmark region (no orphaned content)

Severity guide:

• Major: No <main> landmark
• Minor: Secondary nav without aria-label

2.9 Dynamic Content (WCAG 4.1.3)

• Toast/notification content uses aria-live="polite" or role="status"
• Urgent alerts use aria-live="assertive" or role="alert"
• Loading states are announced (aria-busy="true", status updates)
• Inline content updates (counters, live data) use aria-live
• Infinite scroll / lazy load triggers are keyboard accessible

Severity guide:

• Major: Alert message not announced to screen reader
• Minor: Loading state not announced

2.10 Touch and Pointer (WCAG 2.5.5, 2.5.8)

• Touch targets are at least 44x44 CSS pixels
• Touch targets have adequate spacing (no overlapping hit areas)
• Drag interactions have keyboard alternatives
• Hover-revealed content can also be triggered by focus

Severity guide:

• Major: Touch target below 44x44px for primary actions
• Minor: Touch target below 44x44px for secondary actions

Step 3: Produce the Report

Format the report as follows:

# Accessibility Audit Report

**Scope**: [files/directories audited]
**Date**: [current date]
**Standard**: WCAG 2.1 Level AA

## Summary

| Severity | Count |
|----------|-------|
| Critical | X     |
| Major    | X     |
| Minor    | X     |

**Overall rating**: [Pass / Conditional Pass / Fail]
- Pass: 0 Critical, 0 Major
- Conditional Pass: 0 Critical, ≤3 Major
- Fail: Any Critical findings

## Critical Findings

### [C1] Missing keyboard access on dropdown menu
- **File**: `src/components/Dropdown.tsx:45`
- **WCAG**: 2.1.1 Keyboard (Level A)
- **Issue**: The dropdown menu opens on `onClick` but has no `onKeyDown` handler. Keyboard users cannot open the menu.
- **Fix**:
  ```tsx
  // Add keyboard handler
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault();
      setOpen(!open);
    }
  }}

• axe-core rule: keyboard

Major Findings

[Same format as above]

Minor Findings

[Same format as above]

Passed Checks

[List categories that passed with no findings]

## Step 4: Provide Fix Priority

After the report, provide a prioritized fix list:

Recommended Fix Order

1. [C1] Keyboard access on dropdown — blocks all keyboard users
2. [C2] Focus trap in modal — blocks keyboard/screen reader users
3. [M1] Missing alt text on product images — affects screen reader users ...

## axe-core Rule Mapping

When a finding maps to an axe-core rule, include the rule ID so the team can set up automated checks. Common mappings:
- `image-alt` — images must have alt text
- `button-name` — buttons must have accessible names
- `label` — form elements must have labels
- `color-contrast` — text must meet contrast ratios
- `aria-required-attr` — ARIA roles must have required attributes
- `aria-valid-attr-value` — ARIA attributes must have valid values
- `keyboard` — interactive elements must be keyboard accessible
- `focus-order-semantics` — focus order must be logical
- `region` — content must be in landmark regions

## Notes

- When in doubt about severity, err on the side of higher severity.
- Always provide the concrete fix — don't just say "add alt text", show the actual code change.
- If a component is used in multiple places, note the multiplied impact.
- Flag any patterns that suggest systemic issues (e.g., "none of the form inputs have labels" suggests a pattern problem, not just individual findings).