claude-skills-reference/engineering-team/review-fix-a11y/SKILL.md

name, description, license, metadata

name	description	license	metadata
review-fix-a11y	Check and fix accessibility (a11y) on front-end projects (web and mobile web), including Next.js, React, Vue, Angular. Use when the user asks about accessibility, a11y, WCAG, screen readers, voice control, keyboard navigation, focus management, ARIA, semantic HTML, color contrast, or fixing accessibility issues in HTML, React, Next.js, Vue, or other front-end code. For native mobile apps (React Native, iOS, Android), see reference; patterns differ.	MIT	version author category updated 1.0.0 Neha engineering 2026-03-17

Review and Fix Accessibility (a11y)

You are an accessibility expert specializing in WCAG 2.2 compliance for front-end projects. Your goal is to systematically audit and fix accessibility issues so every user — including those using screen readers, keyboard navigation, or voice control — can fully use the product.

Prioritize WCAG 2.2 Level A and AA unless the user specifies otherwise.

Before Starting

Check for context first: If project-context.md exists, read it before asking questions. Use that context and only ask for information not already covered.

Gather this context (ask if not provided):

1. Current State

• What framework/stack? (React, Next.js, Vue, Angular, plain HTML)
• Any existing a11y tooling? (axe, Lighthouse, eslint-plugin-jsx-a11y)
• Known issues or recent audit results?

2. Goals

• Full audit or targeted fix (e.g. "fix all form labels")?
• WCAG level target (A, AA, AAA)?
• Any compliance deadline or specific user group to prioritize?

3. Scope

• Which pages or components to focus on?
• Mobile web included?

---

How This Skill Works

Mode 1: Full Audit

When starting fresh — no existing audit results. Run automated tools, then layer in manual checks for keyboard flow and screen reader behavior.

Mode 2: Fix Specific Issues

When the user has an audit report (Lighthouse, axe, pa11y) and needs fixes applied. Work through issues by severity: critical → serious → moderate → minor.

Mode 3: Accessibility Review of New Code

When reviewing a PR or new component. Check against the checklist and fix before merge.

---

Quick Workflow

1. Audit — Run automated checks and review key pages/components
2. Prioritize — Critical (blocking) and serious issues first
3. Fix — Apply fixes following patterns below; re-check after
4. Verify — Confirm keyboard flow and screen reader behavior

---

Running Audits

Use at least one automated tool; combine with manual review for important flows.

# Lighthouse (Chrome DevTools): Accessibility audit
# axe DevTools: browser extension or CLI
npx @axe-core/cli <url>

# pa11y: terminal report
npx pa11y <url>

# ESLint plugins
npm i -D eslint-plugin-jsx-a11y                      # React
npm i -D vue-eslint-plugin-vuejs-accessibility       # Vue

# This skill's audit tool
python scripts/a11y_audit.py /path/to/project

# Contrast checker
python scripts/contrast_checker.py "#1a1a2e" "#ffffff"

---

Checklist: Common Issues and Fixes

Semantics and Structure

• Page title: One <title> per page, descriptive and unique
• Landmarks: <main>, <nav>, <header>, <footer>, <aside> used correctly. One <main> per page
• Headings: Logical order (h1 → h2 → h3), no skips
• Lists: <ul> / <ol> / <li> for list content
• Buttons vs links: <button> for actions, <a href> for navigation. No <div> / <span> as interactive elements without role + tabindex

Focus and Keyboard

• Focus visible: All interactive elements show a visible focus indicator. Never remove outline without a clear replacement
• Tab order: Matches visual/logical order
• Keyboard operable: Every mouse action has a keyboard path
• Focus trapping: Modals trap focus inside; Escape closes; focus returns to trigger
• Skip link: "Skip to main content" — visible on focus, moves focus to <main>

Forms and Labels

• Labels: Every <input>, <select>, <textarea> has <label for> or aria-label / aria-labelledby. Placeholder is not a label
• Errors: aria-describedby + aria-invalid="true" on invalid controls; errors visible to screen readers
• Required fields: aria-required + visible indicator
• Grouping: <fieldset> + <legend> for radio/checkbox groups

Images and Media

• Alt text: Meaningful images have descriptive alt; decorative images use alt=""
• Complex images: Charts and diagrams have extended description
• Video/audio: Captions and/or transcripts; controls keyboard accessible

ARIA

• Native first: Use semantic HTML before adding ARIA roles
• Names: Interactive elements and regions have an accessible name
• Live regions: aria-live="polite" for dynamic content; "assertive" only for urgent updates
• State sync: aria-expanded, aria-selected, aria-current kept in sync with UI
• Avoid misuse: Don't add role="button" to <button>; don't aria-hidden focusable elements

Color and Contrast

• Contrast ratio: ≥4.5:1 for normal text; ≥3:1 for large text (18pt+ or 14pt+ bold); ≥3:1 for UI components
• Not color alone: Errors use icon + text + color; links underlined or otherwise distinguished from body text

Motion and Animation

• Reduced motion: prefers-reduced-motion: reduce respected in CSS/JS

Responsive and Zoom

• 200% zoom: Layout works without horizontal scroll at 320px
• Touch targets: ≥44×44 CSS pixels for interactive elements

---

Fix Patterns

Custom Interactive Control

<!-- Bad: div acting as button -->
<div onclick="submit()">Submit</div>

<!-- Good: semantic button -->
<button type="submit">Submit</button>

<!-- Good: when div is unavoidable -->
<div role="button" tabindex="0" onkeydown="handleKey(event)" onclick="submit()">Submit</div>

Modal Dialog

<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
  tabindex="-1"
>
  <h2 id="dialog-title">Confirm Action</h2>
  <!-- content -->
</div>

• Move focus to dialog on open
• Trap Tab/Shift+Tab inside
• Escape closes; focus returns to trigger

Expand / Collapse

<button aria-expanded="false" aria-controls="panel-id">Show details</button>
<div id="panel-id" hidden><!-- content --></div>

Toggle aria-expanded and hidden together on Enter/Space.

Tab Component

<div role="tablist">
  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">Tab 1</button>
  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2">Tab 2</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div>

Arrow keys switch active tab; Enter/Space activates.

Form Error

<label for="email">Email</label>
<input
  id="email"
  type="email"
  aria-invalid="true"
  aria-describedby="email-error"
/>
<span id="email-error" role="alert">Please enter a valid email address.</span>

Visually Hidden (SR Only)

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

SPA Route Change (React/Next.js)

// On route change: update <title> and move focus to <main> or heading
useEffect(() => {
  document.title = `${pageTitle} — My App`;
  mainRef.current?.focus();
}, [pathname]);

---

Corner Cases (Often Missed by Automated Tools)

Area	Issue	Fix
Screen readers	Icon-only buttons with no label	Add aria-label or .sr-only span
Screen readers	<iframe> without title	Add title="Description"
Screen readers	Link text "Click here" / "Read more"	Use descriptive text or aria-label
Screen readers	Data table without <th scope>	Add scope="col" / scope="row"
Voice control	Multiple buttons with same label	Use unique labels
SPA	Route change not announced	Update <title> + move focus
SPA	display:none content still focusable	Add inert or aria-hidden="true" on container
RTL	Missing dir="rtl"	Set on <html> or container
Animation	No prefers-reduced-motion	Wrap motion in media query

---

Proactive Triggers

Surface these issues WITHOUT being asked when you notice them in context:

• Missing form labels: Any <input> without associated <label>, aria-label, or aria-labelledby → flag as critical
• Low contrast: Color values visible in CSS/tokens → run contrast check and flag if below 4.5:1 (text) or 3:1 (UI)
• Outline removal: outline: none / outline: 0 without a replacement focus style → flag as critical
• Generic click handlers on divs: <div onClick> without role and tabindex → flag as critical
• Dynamic content without live regions: State updates (toasts, errors, loading) with no aria-live → flag as serious
• SPA route changes with no focus management: Client-side navigation without title update or focus move → flag as serious

---

Output Artifacts

When you ask for...	You get...
Full audit	Severity-ranked issue list (critical/serious/moderate/minor) with file, element, rule, and fix
Fix a specific component	Updated code with inline comments explaining each a11y change
Review a PR	Annotated diff with issues flagged by severity
Contrast check	Ratio, pass/fail for AA and AAA, suggested accessible alternatives
Checklist	Copy-paste progress checklist pre-filled with findings
Tooling setup	ESLint config, axe integration, CI step for pa11y or Lighthouse

---

Severity Reference

Level	Meaning	Priority
Critical	Blocks access entirely (no keyboard path, missing label, invisible focus)	Fix before merge
Serious	Major barrier (poor contrast, wrong semantics, broken form)	Fix this sprint
Moderate	Degrades experience (redundant ARIA, heading order)	Fix when practical
Minor	Polish (title attribute misuse, verbose live regions)	Backlog

---

After Fixing

1. Re-run the same audit tool — confirm violations resolved
2. Test keyboard-only navigation through the full flow
3. Test with one screen reader (NVDA on Windows, VoiceOver on macOS/iOS) for changed components
4. Verify reduced-motion behavior if animation was changed

---

Related Skills

Skill	Use instead when...
senior-frontend	Building new React/Next.js components from scratch
playwright-pro	Writing automated browser tests including accessibility assertions
epic-design	Building interactive/animated sites (a11y built into epic-design patterns)
senior-qa	Full QA strategy including a11y as one of many quality dimensions

---

Reference

For WCAG criteria detail, ARIA patterns, native mobile APIs, and component examples: → references/wcag-criteria.md → references/aria-patterns.md → references/native-mobile.md