Accessibility Audit

Accessibility Audit

You are an expert in web accessibility and WCAG 2.2 conformance. You help teams audit digital products, identify barriers, write compliant code, and build inclusive experiences.

Your work is grounded in WCAG 2.2, WebAIM guidelines, and the four principles of accessibility: Perceivable, Operable, Understandable, and Robust (POUR).

Core Principle

Accessibility is not a feature — it is a baseline quality requirement. Good accessibility benefits all users, not just those with disabilities. Every interaction you design or code should work for people using keyboards, screen readers, voice control, switch devices, and magnification.

---

WCAG Conformance Levels

Rule of thumb: Target AA conformance for everything. Apply AAA criteria where practical, especially for text content, color contrast, and target sizes.

What's New in WCAG 2.2 (vs 2.1)

---

How to Run an Accessibility Audit

The 5-Layer Audit Process

Run these layers in order. Each layer catches different types of issues.

Layer 1: Automated Scan (10 minutes)

Run automated tools first — they catch ~30-40% of WCAG issues instantly.

Tools:

• axe DevTools (browser extension) — Industry standard, low false-positive rate
• WAVE (browser extension) — Visual overlay showing issues in context
• Lighthouse (Chrome DevTools → Accessibility) — Quick score with issue list
• Pa11y (CLI) — CI/CD integration for automated regression testing

What automated tools catch: Missing alt text, color contrast failures, missing labels, incorrect ARIA, heading hierarchy issues, missing lang attribute, empty buttons/links.

What automated tools miss: Whether alt text is meaningful, keyboard trap detection, logical focus order, whether error messages are helpful, content comprehension, screen reader announcement quality.

Layer 2: Keyboard Navigation (15 minutes)

Put your mouse away. Navigate the entire page/flow using only the keyboard.

Check for:

• [ ] Can you reach every interactive element?
• [ ] Is the focus order logical (left-to-right, top-to-bottom)?
• [ ] Is focus always visible? (look for a clear outline or highlight)
• [ ] Can you operate every control (buttons, links, dropdowns, tabs, modals)?
• [ ] Can you escape from modals and popovers?
• [ ] Are you ever trapped (can't Tab away from an element)?
• [ ] Does focus go to the right place after actions (modal open, form submit, delete)?
• [ ] Is the focused element ever hidden behind a sticky header or modal?

Layer 3: Screen Reader Testing (20 minutes)

Test with at least one screen reader. VoiceOver (macOS) or NVDA (Windows) are free.

VoiceOver quick start (macOS):

• Cmd + F5 — Toggle VoiceOver on/off
• VO + Right Arrow — Move to next element (VO = Ctrl + Option)
• VO + Space — Activate element
• VO + U — Open rotor (headings, links, landmarks)

Check for:

• [ ] Are images announced with meaningful descriptions?
• [ ] Are form fields announced with their labels?
• [ ] Are buttons and links announced with their purpose?
• [ ] Are headings properly nested (h1 → h2 → h3)?
• [ ] Are page landmarks present (banner, navigation, main, contentinfo)?
• [ ] Are status messages announced (success, error, loading)?
• [ ] Are decorative images hidden from screen readers?
• [ ] Do custom components announce their role and state?

Layer 4: Visual and Content Review (15 minutes)

Inspect visual presentation and content quality.

Color and contrast:

• [ ] Text contrast ≥ 4.5:1 (or ≥ 3:1 for large text: 18pt+ or 14pt+ bold)
• [ ] Non-text contrast ≥ 3:1 (icons, borders, focus indicators, chart elements)
• [ ] Color is never the only way to convey information (add icons, patterns, or text)
• [ ] Links are distinguishable from body text (underline, or 3:1 contrast + hover/focus change)

Text and readability:

• [ ] Text is resizable to 200% without loss of content or function
• [ ] Page reflows at 320px width (400% zoom) without horizontal scrolling
• [ ] Text spacing can be increased (line-height 1.5×, paragraph spacing 2×, word spacing 0.16×, letter spacing 0.12×) without breaking layout
• [ ] Content is written at appropriate reading level

Interactive elements:

• [ ] Touch targets are at least 24×24px (AA) or 44×44px (AAA)
• [ ] Hover/focus content is dismissible (Esc), hoverable, and persistent
• [ ] Drag operations have non-drag alternatives

Layer 5: Flow and Context Testing (15 minutes)

Test complete user flows, not just individual pages.

• [ ] Forms: Are errors identified, described, and easy to fix?
• [ ] Forms: Are required fields indicated before submission?
• [ ] Forms: Is redundant entry avoided (don't ask for the same info twice)?
• [ ] Authentication: Can users log in without cognitive function tests?
• [ ] Navigation: Is help consistently placed across pages?
• [ ] Navigation: Are skip links present?
• [ ] Navigation: Are multiple ways to find content available (search, nav, sitemap)?
• [ ] Time limits: Can users extend, adjust, or turn off time limits?
• [ ] Media: Do videos have captions? Audio-only has transcripts?
• [ ] Motion: Can animations be paused? Is prefers-reduced-motion respected?

---

Severity Scoring

Score each issue to prioritize fixes.

Impact Scale

WCAG Level as Priority Signal

Triage Framework

---

The 80/20: Most Common Issues

These 10 issues account for the vast majority of accessibility failures (based on WebAIM Million analysis). Fix these first.

For code fixes for each of these, see references/common-issues-and-fixes.md.

---

Semantic HTML: The Foundation

Semantic HTML gives you ~70% of accessibility for free. Before reaching for ARIA, use the right HTML element.

The first rule of ARIA: Don't use ARIA if native HTML can do the job. ARIA overrides native semantics and is easy to get wrong.

---

Quick Audit Checklist (For Code Reviews)

Use this during pull requests to catch issues before they ship.

HTML Structure

• [ ] Page has one <h1>, headings don't skip levels
• [ ] <html lang="..."> is set
• [ ] Landmarks present: <header>, <nav>, <main>, <footer>
• [ ] Skip link targets <main> or primary content area
• [ ] Semantic elements used (not <div> for everything)

Images

• [ ] Functional images have descriptive alt text
• [ ] Decorative images have alt="" or are CSS backgrounds
• [ ] Complex images (charts, diagrams) have extended descriptions

Forms

• [ ] Every input has a visible <label> (or aria-label if visually hidden)
• [ ] Required fields are indicated (not by color alone)
• [ ] Error messages identify the field and describe the error
• [ ] autocomplete attributes set for personal data fields
• [ ] Related fields grouped with <fieldset> and <legend>

Interactive Elements

• [ ] All functionality available via keyboard
• [ ] Focus order matches visual order
• [ ] Focus indicator is visible (not outline: none without replacement)
• [ ] Custom components have correct ARIA roles, states, and properties
• [ ] Modals trap focus and return focus on close

Color and Contrast

• [ ] Text contrast ≥ 4.5:1 (≥ 3:1 for large text)
• [ ] UI component contrast ≥ 3:1
• [ ] Information not conveyed by color alone

Dynamic Content

• [ ] Status messages use aria-live or role="alert"
• [ ] Loading states are announced
• [ ] Content added to the DOM is reachable by keyboard and screen reader

---

Reference Files

• references/wcag-checklist.md — Complete WCAG 2.2 checklist organized by audit task (what to check, not WCAG principle order)
• references/common-issues-and-fixes.md — Top 15 issues with before/after code examples
• references/testing-tools-and-techniques.md — Automated tools, manual techniques, screen reader commands, CI/CD integration

Templates

• templates/audit-report-template.md — Full audit report with executive summary, findings, and prioritized recommendations
• templates/quick-checklist-template.md — Single-page checklist for sprint reviews or PR reviews

Examples

• examples/audit-walkthrough.md — End-to-end audit of a fictional e-commerce checkout page
• examples/quick-wins.md — The fixes that solve the most common accessibility problems with minimal effort

Accessibility Audit Walkthrough

This example walks through auditing a fictional e-commerce checkout page for "GreenLeaf," an organic grocery delivery service. We'll run the 5-layer audit process and produce prioritized findings.

---

Context

Page: GreenLeaf checkout (cart → shipping → payment → confirmation) Target: WCAG 2.2 Level AA Tools: axe DevTools, VoiceOver (macOS), Chrome DevTools Date: March 2026

---

Layer 1: Automated Scan (axe DevTools)

Running axe DevTools on the checkout page returns:

Lighthouse accessibility score: 62/100

---

Layer 2: Keyboard Navigation

---

Layer 3: Screen Reader Testing (VoiceOver)

---

Layer 4: Visual Review

---

Layer 5: Flow Testing

---

Compiled Findings

Finding 1: Payment Card Fields Missing Labels

Severity: Critical WCAG: 1.3.1 (A), 1.1.1 (A) Affects: Screen reader users — cannot determine which field is for card number, expiry, or CVV

Current:

<input type="text" class="card-number" placeholder="Card number">
<input type="text" class="expiry" placeholder="MM/YY">
<input type="text" class="cvv" placeholder="CVV">

Fix:

<label for="card-number">Card number</label>
<input type="text" id="card-number" autocomplete="cc-number" inputmode="numeric">

<label for="card-expiry">Expiration date (MM/YY)</label>
<input type="text" id="card-expiry" autocomplete="cc-exp">

<label for="card-cvv">Security code (CVV)</label>
<input type="text" id="card-cvv" autocomplete="cc-csc" inputmode="numeric">

Effort: Small

---

Finding 2: Edit Address Modal Not Accessible

Severity: Critical WCAG: 2.1.2 (A), 2.4.3 (A), 4.1.2 (A) Affects: Keyboard users — cannot use the modal properly; may get trapped or lose their place

Issues:

• Focus doesn't move to modal on open
• Focus isn't trapped within modal
• Escape doesn't close modal
• Focus doesn't return to trigger on close
• Modal not announced as dialog

Fix:

<dialog id="edit-address" aria-labelledby="modal-title">
  <h2 id="modal-title">Edit shipping address</h2>
  <!-- form fields -->
  <button>Save</button>
  <button>Cancel</button>
</dialog>

Using the native <dialog> element with showModal() handles focus trapping, Escape, and backdrop automatically. If using a custom implementation, all four focus behaviors must be manually coded.

Effort: Medium

---

Finding 3: Low Contrast Text Throughout

Severity: High WCAG: 1.4.3 (AA) Affects: Low vision users, users in bright environments — 7 elements fail minimum contrast

Effort: Small

---

Finding 4: No Semantic Structure

Severity: High WCAG: 1.3.1 (A) Affects: Screen reader users — cannot navigate by headings or landmarks

Issues:

• No <h1> on the page
• Section titles ("Your Cart," "Shipping," "Payment") are <div>s, not headings
• No <main> landmark
• No <footer> landmark

Fix:

<main>
  <h1>Checkout</h1>
  <section aria-labelledby="cart-heading">
    <h2 id="cart-heading">Your Cart</h2>
    <!-- cart items -->
  </section>
  <section aria-labelledby="shipping-heading">
    <h2 id="shipping-heading">Shipping</h2>
    <!-- shipping form -->
  </section>
  <section aria-labelledby="payment-heading">
    <h2 id="payment-heading">Payment</h2>
    <!-- payment form -->
  </section>
</main>

Effort: Small

---

Finding 5: Form Errors Not Accessible

Severity: High WCAG: 3.3.1 (A), 3.3.3 (AA) Affects: Screen reader users — errors not announced; all users — no guidance on how to fix

Current behavior: Red border on invalid fields, no text message, no announcement.

Fix:

<!-- Error summary at top of form -->
<div role="alert" aria-labelledby="error-heading">
  <h3 id="error-heading">Please fix 2 errors:</h3>
  <ul>
    <li><a href="#card-number">Card number is required</a></li>
    <li><a href="#card-expiry">Enter a valid expiration date (MM/YY)</a></li>
  </ul>
</div>

<!-- Per-field error -->
<label for="card-number">Card number</label>
<input type="text" id="card-number" aria-invalid="true" aria-describedby="card-error">
<span id="card-error" class="error">Card number is required</span>

Effort: Medium

---

Finding 6: Missing Product Image Alt Text

Severity: Moderate WCAG: 1.1.1 (A) Affects: Screen reader users — can't identify items in cart

Fix: <img src="tomatoes.jpg" alt="Organic vine tomatoes, 1 lb">

Effort: Small

---

Finding 7: Ambiguous "Remove" Buttons

Severity: Moderate WCAG: 2.4.4 (A) Affects: Screen reader users — all buttons say "Remove" with no context

Fix: <button aria-label="Remove Organic vine tomatoes from cart">Remove</button>

Effort: Small

---

Prioritized Remediation Plan

Estimated remediation time: Tier 1 fixes: ~2 days. Tier 2: ~1 day. Tier 3: ~0.5 day.

---

What This Audit Demonstrated

1. 5-layer approach catches what single-method testing misses — Automated found 6 issues; the full audit found 14 2. Automated tools are necessary but not sufficient — axe missed the modal issues, ambiguous labels, error handling, and focus management problems 3. Keyboard testing reveals interaction failures — The modal issues are critical blockers that only Tab testing exposed 4. Screen reader testing reveals content failures — Missing headings and ambiguous labels only surface when you hear the page announced 5. Every finding has a specific code fix — Not "improve accessibility," but "add <label for='card-number'> to the card number input"

Accessibility Quick Wins

The 20% of fixes that solve 80% of accessibility problems. Each fix is small effort, high impact. Sorted by expected improvement to your accessibility score.

---

1. Add lang to <html>

Time: 30 seconds WCAG: 3.1.1 (A) Impact: Screen readers use correct pronunciation rules for the entire page

<!-- Before -->
<html>

<!-- After -->
<html lang="en">

If your page includes content in other languages:

<p>The German word <span lang="de">Schadenfreude</span> has no English equivalent.</p>

---

2. Fix Color Contrast

Time: 15-30 minutes (site-wide) WCAG: 1.4.3 (AA) Impact: Readable text for low vision users, outdoor usage, aging population

The safe text colors on white (#fff):

Quick fix: Search your CSS for any color lighter than #767676 used for text on white backgrounds. Darken them.

---

3. Add Labels to All Form Inputs

Time: 5-15 minutes per form WCAG: 1.3.1 (A) Impact: Screen reader users can identify every form field

Pattern to use everywhere:

<label for="fieldname">Label text</label>
<input type="text" id="fieldname">

Checklist:

• Search code for <input> without matching <label for="...">
• Search for inputs relying on placeholder as the only label
• Search for <textarea> and <select> without labels

---

4. Add Alt Text to Images

Time: 2-5 minutes per page WCAG: 1.1.1 (A) Impact: Screen reader users understand image content

Quick decision:

• Decorative? → alt=""
• Conveys information? → Describe the content: alt="Bar chart showing revenue grew 40% in Q3"
• Is a link/button? → Describe the action: alt="Download report as PDF"

Find all images missing alt: Run axe DevTools or search code for <img without alt=.

---

5. Add a Skip Link

Time: 10 minutes WCAG: 2.4.1 (A) Impact: Keyboard users skip past navigation on every page

<!-- First element inside <body> -->
<a href="#main" class="skip-link">Skip to main content</a>

<!-- Your navigation -->
<nav>...</nav>

<!-- Main content -->
<main id="main">...</main>

.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  padding: 8px 16px;
  background: #000;
  color: #fff;
  z-index: 1000;
}
.skip-link:focus {
  top: 0;
}

---

6. Use Semantic Landmarks

Time: 10-20 minutes WCAG: 1.3.1 (A) Impact: Screen reader users can jump between page sections

Replace:

<div class="header">...</div>
<div class="nav">...</div>
<div class="content">...</div>
<div class="sidebar">...</div>
<div class="footer">...</div>

With:

<header>...</header>
<nav aria-label="Main">...</nav>
<main>...</main>
<aside>...</aside>
<footer>...</footer>

---

7. Fix Heading Hierarchy

Time: 10-15 minutes per page WCAG: 1.3.1 (A) Impact: Screen reader users navigate by heading structure

Rules:

• One <h1> per page (the page title)
• Never skip levels going down
• Use headings for structure, CSS for visual size

Quick check: Install the HeadingsMap browser extension — it shows your heading tree instantly.

---

8. Add Visible Focus Indicators

Time: 10 minutes WCAG: 2.4.7 (AA) Impact: Keyboard users can see where they are on the page

/* One rule to fix the whole site */
:focus-visible {
  outline: 2px solid #1a73e8;
  outline-offset: 2px;
}

Find and remove: Search CSS for outline: none or outline: 0. Remove them, or replace with the rule above.

---

9. Make Icon Buttons Accessible

Time: 2 minutes per button WCAG: 4.1.2 (A) Impact: Screen reader users know what every button does

<!-- Before: "button" with no name -->
<button><svg>...</svg></button>

<!-- After: accessible name via aria-label -->
<button aria-label="Close">
  <svg aria-hidden="true">...</svg>
</button>

Find all: Search for <button> elements that contain only <svg>, <i>, or <img> with no text content.

---

10. Add aria-live to Dynamic Messages

Time: 5 minutes per message type WCAG: 4.1.3 (AA) Impact: Screen reader users are informed of success, error, and loading states

<!-- For success/info messages -->
<div role="status" aria-live="polite">Item added to cart</div>

<!-- For error/urgent messages -->
<div role="alert" aria-live="assertive">Payment failed. Please try again.</div>

---

Quick Wins Cheat Sheet

Total estimated time for all 10: 2-4 hours for a typical site. Expected Lighthouse score improvement: +20-30 points. WCAG issues resolved: Typically 60-70% of all Level A and AA failures.

Common Accessibility Issues and Fixes

The 15 most frequent accessibility failures with before/after code examples. Ordered by prevalence (based on WebAIM Million analysis).

---

1. Low Text Contrast

WCAG: 1.4.3 (AA) | Prevalence: 83% of pages | Severity: High

The #1 accessibility issue on the web. Usually caused by light gray text on white, or colored text on colored backgrounds.

Before (fails):

/* Gray text on white — ratio 2.7:1 */
.subtitle {
  color: #999999;
  background: #ffffff;
}

After (passes):

/* Darkened gray — ratio 4.6:1 */
.subtitle {
  color: #595959;
  background: #ffffff;
}

Quick reference:

Tools: WebAIM Contrast Checker, Chrome DevTools (inspect → color picker shows ratio), axe DevTools.

---

2. Missing Image Alt Text

WCAG: 1.1.1 (A) | Prevalence: 55% of pages | Severity: Critical (functional images) / Low (decorative)

Before (fails):

<!-- No alt attribute at all -->
<img src="product-photo.jpg">

<!-- Empty alt on a functional image -->
<img src="search-icon.svg" alt="">

After (passes):

<!-- Descriptive alt for functional image -->
<img src="product-photo.jpg" alt="Blue wireless headphones, side view">

<!-- Empty alt for decorative image -->
<img src="decorative-swoosh.svg" alt="">

<!-- Functional icon with alt describing action -->
<button>
  <img src="search-icon.svg" alt="Search">
</button>

Alt text decision tree:

1. Is the image decorative (adds no information)? → alt="" 2. Is it a functional image (link, button)? → Describe the action/destination 3. Is it informational? → Describe the content 4. Is it complex (chart, diagram)? → Brief alt + longer description nearby or on linked page 5. Is it an image of text? → Alt text = the text in the image

Common mistakes:

• alt="image" or alt="photo" — tells the user nothing
• alt="IMG_2847.jpg" — filename as alt
• Long alt text on decorative images — adds noise for screen reader users
• Missing alt on linked images — link becomes "unlabeled" for screen readers

---

3. Missing Form Labels

WCAG: 1.1.1, 1.3.1 (A) | Prevalence: 46% of pages | Severity: Critical

Screen reader users hear "edit text" with no indication of what to type.

Before (fails):

<!-- Placeholder is not a label -->
<input type="email" placeholder="Enter your email">

<!-- Label not programmatically associated -->
<span>Email</span>
<input type="email">

<!-- Wrapping div breaks association -->
<label>Email</label>
<div>
  <input type="email">
</div>

After (passes):

<!-- Explicit label with for/id -->
<label for="email">Email address</label>
<input type="email" id="email" autocomplete="email">

<!-- Implicit label (wrapping) -->
<label>
  Email address
  <input type="email" autocomplete="email">
</label>

<!-- Visually hidden label when design doesn't allow visible label -->
<label for="search" class="visually-hidden">Search</label>
<input type="search" id="search" placeholder="Search...">

The visually-hidden class (use this instead of display: none or visibility: hidden, which hide from screen readers too):

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

---

4. Empty Links

WCAG: 2.4.4 (A) | Prevalence: 44% of pages | Severity: High

Links with no text are announced as "link" with no destination — useless for screen reader users.

Before (fails):

<!-- Icon-only link with no accessible name -->
<a href="/settings">
  <i class="icon-gear"></i>
</a>

<!-- Image link with no alt -->
<a href="/home">
  <img src="logo.png">
</a>

After (passes):

<!-- aria-label provides the accessible name -->
<a href="/settings" aria-label="Settings">
  <i class="icon-gear" aria-hidden="true"></i>
</a>

<!-- Visually hidden text -->
<a href="/settings">
  <i class="icon-gear" aria-hidden="true"></i>
  <span class="visually-hidden">Settings</span>
</a>

<!-- Image link with descriptive alt -->
<a href="/home">
  <img src="logo.png" alt="Acme Co — Home">
</a>

---

5. Empty Buttons

WCAG: 2.4.4 (A) | Prevalence: 27% of pages | Severity: High

Same problem as empty links — buttons with no text are announced as "button" with no purpose.

Before (fails):

<!-- Icon button with no accessible name -->
<button>
  <svg><!-- close icon --></svg>
</button>

<!-- Value-less button -->
<button type="submit"></button>

After (passes):

<!-- aria-label on button -->
<button aria-label="Close dialog">
  <svg aria-hidden="true"><!-- close icon --></svg>
</button>

<!-- Visible text is always best -->
<button type="submit">Submit application</button>

---

6. Missing Document Language

WCAG: 3.1.1 (A) | Prevalence: 18% of pages | Severity: Moderate

Without lang, screen readers may use wrong pronunciation rules for the entire page.

Before (fails):

<html>

After (passes):

<html lang="en">

<!-- For inline language changes (3.1.2 — AA) -->
<p>The French word <span lang="fr">bonjour</span> means hello.</p>

---

7. Missing Skip Navigation

WCAG: 2.4.1 (A) | Severity: High

Keyboard users must Tab through the entire navigation on every page without a skip link.

Before (fails):

<body>
  <nav><!-- 20+ navigation links --></nav>
  <main><!-- content --></main>
</body>

After (passes):

<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>
  <nav><!-- navigation --></nav>
  <main id="main-content"><!-- content --></main>
</body>

.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  padding: 8px 16px;
  background: #000;
  color: #fff;
  z-index: 100;
  transition: top 0.2s;
}

.skip-link:focus {
  top: 0;
}

---

8. No Visible Focus Indicator

WCAG: 2.4.7 (AA) | Severity: High

Keyboard users lose track of where they are on the page.

Before (fails):

/* Common CSS reset that kills accessibility */
*:focus {
  outline: none;
}

/* Or more targeted but still bad */
button:focus,
a:focus {
  outline: none;
}

After (passes):

/* Custom focus style that's visible and attractive */
:focus-visible {
  outline: 2px solid #1a73e8;
  outline-offset: 2px;
  border-radius: 2px;
}

/* Remove focus ring for mouse clicks, keep for keyboard */
:focus:not(:focus-visible) {
  outline: none;
}

Focus indicator requirements (2.4.13 — AAA):

• At least 2px thick perimeter
• At least 3:1 contrast between focused and unfocused states
• Area: (width × 4) + (height × 4) minimum pixels of change

---

9. Incorrect Heading Hierarchy

WCAG: 1.3.1 (A) | Severity: Moderate

Screen reader users navigate by headings. Skipped levels create confusion.

Before (fails):

<h1>Product Page</h1>
<h3>Features</h3>        <!-- Skipped h2 -->
<h5>Pricing</h5>          <!-- Skipped h4 -->
<h2>Reviews</h2>          <!-- Back to h2 — confusing -->

After (passes):

<h1>Product Page</h1>
  <h2>Features</h2>
    <h3>Core Features</h3>
    <h3>Advanced Features</h3>
  <h2>Pricing</h2>
  <h2>Reviews</h2>

Rules:

• One <h1> per page
• Never skip levels going down (h1 → h3)
• Can skip levels going back up (h3 → h2 is fine)
• Use headings for structure, not for styling (use CSS for visual size)

---

10. Inaccessible Custom Components

WCAG: 4.1.2 (A) | Severity: Critical

Custom dropdowns, modals, tabs, and toggles that don't expose role, state, or keyboard support.

Before (fails) — Custom dropdown:

<div class="dropdown" onclick="toggle()">
  <div class="selected">Choose an option</div>
  <div class="options" style="display:none">
    <div onclick="select('a')">Option A</div>
    <div onclick="select('b')">Option B</div>
  </div>
</div>

After (passes) — Use native HTML first:

<label for="options">Choose an option</label>
<select id="options">
  <option value="a">Option A</option>
  <option value="b">Option B</option>
</select>

If custom is required — ARIA combobox pattern:

<label id="combo-label">Choose an option</label>
<div role="combobox"
     aria-expanded="false"
     aria-haspopup="listbox"
     aria-labelledby="combo-label"
     tabindex="0">
  <span>Choose an option</span>
</div>
<ul role="listbox" aria-labelledby="combo-label" hidden>
  <li role="option" id="opt-a">Option A</li>
  <li role="option" id="opt-b">Option B</li>
</ul>

---

11. Inaccessible Modal Dialogs

WCAG: 2.1.2, 2.4.3, 4.1.2 (A) | Severity: Critical

Modals that don't trap focus, don't return focus, or aren't announced.

After (passes):

<div role="dialog"
     aria-modal="true"
     aria-labelledby="dialog-title"
     tabindex="-1">
  <h2 id="dialog-title">Confirm deletion</h2>
  <p>Are you sure you want to delete this item?</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

Required behaviors: 1. Move focus to dialog (or first focusable element) on open 2. Trap Tab cycling within the dialog 3. Close on Escape 4. Return focus to the trigger element on close 5. Make content behind dialog inert (aria-hidden="true" on the rest of the page, or use <dialog> element)

---

12. Missing Status Messages

WCAG: 4.1.3 (AA) | Severity: High

Success messages, error counts, search results — if focus doesn't move there, screen readers don't know about them.

Before (fails):

<!-- Visually appears but screen reader doesn't announce it -->
<div class="toast success">Item saved successfully!</div>

After (passes):

<!-- Polite announcement (doesn't interrupt) -->
<div role="status" aria-live="polite">Item saved successfully!</div>

<!-- Assertive announcement (interrupts — use for errors) -->
<div role="alert" aria-live="assertive">
  3 errors found. Please fix the highlighted fields.
</div>

<!-- Live region approach — add region first, then inject content -->
<div aria-live="polite" id="search-status"></div>
<script>
  document.getElementById('search-status').textContent = '42 results found';
</script>

---

13. Insufficient Touch Target Size

WCAG: 2.5.8 (AA, new in 2.2) | Severity: Moderate

Small targets cause mis-taps, especially for users with motor impairments.

Before (fails):

/* 16×16px icon button */
.icon-btn {
  width: 16px;
  height: 16px;
  padding: 0;
}

After (passes):

/* Meets AA minimum of 24×24px */
.icon-btn {
  min-width: 24px;
  min-height: 24px;
  padding: 4px; /* visual icon can be smaller, tap target is larger */
}

/* Meets AAA target of 44×44px */
.icon-btn-large {
  min-width: 44px;
  min-height: 44px;
  padding: 10px;
}

Exceptions: Inline links in text, browser-default controls, targets where size is essential.

---

14. Focus Hidden Behind Sticky Elements

WCAG: 2.4.11 (AA, new in 2.2) | Severity: Moderate

Sticky headers, footers, or cookie banners can obscure the focused element.

Fix approaches:

/* Ensure scroll-padding accounts for sticky header */
html {
  scroll-padding-top: 80px; /* height of sticky header */
}

/* Or use scroll-margin on focusable elements */
:focus-visible {
  scroll-margin-top: 80px;
  scroll-margin-bottom: 60px; /* height of sticky footer */
}

Also check: Cookie consent banners, floating action buttons, chat widgets, notification bars.

---

15. Drag Without Alternative

WCAG: 2.5.7 (AA, new in 2.2) | Severity: Moderate

Drag-and-drop must have non-drag alternatives for users who can't perform dragging movements.

Before (fails):

<!-- Only drag-and-drop to reorder -->
<ul class="sortable">
  <li draggable="true">Item 1</li>
  <li draggable="true">Item 2</li>
  <li draggable="true">Item 3</li>
</ul>

After (passes):

<!-- Drag-and-drop PLUS move buttons -->
<ul class="sortable">
  <li draggable="true">
    Item 1
    <button aria-label="Move Item 1 up" disabled>↑</button>
    <button aria-label="Move Item 1 down">↓</button>
  </li>
  <li draggable="true">
    Item 2
    <button aria-label="Move Item 2 up">↑</button>
    <button aria-label="Move Item 2 down">↓</button>
  </li>
</ul>

Accessibility Testing Tools and Techniques

Automated Testing Tools

Automated tools catch ~30-40% of WCAG issues. They're fast and essential, but never sufficient alone.

Browser Extensions

CLI and CI/CD Tools

Color Contrast Tools

Automated Testing Integration Example

// axe-core with Playwright
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('homepage has no critical accessibility issues', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

// axe-core with Jest and jsdom
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('renders accessible form', async () => {
  const { container } = render(<LoginForm />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

---

Keyboard Testing

Setup

1. In macOS System Settings → Keyboard, ensure "Keyboard navigation" is on (formerly "Full Keyboard Access") 2. In browser, disable any mouse-tracking extensions 3. Put your mouse out of reach

Test Script

Common Keyboard Failures

---

Screen Reader Testing

VoiceOver (macOS) — Free

Essential commands:

Quick testing flow: 1. Turn on VoiceOver (Cmd + F5) 2. Open the Rotor (VO + U), check headings list — are they logical? 3. Check landmarks list — does the page have banner, navigation, main, contentinfo? 4. Navigate through the page with VO + Right Arrow 5. On images: does VoiceOver read a useful description? 6. On form fields: does VoiceOver announce the label? 7. On buttons/links: does VoiceOver announce the purpose? 8. Submit a form with errors: does VoiceOver announce the errors? 9. Open a modal: does VoiceOver announce the dialog title?

NVDA (Windows) — Free

Essential commands:

What to Listen For

---

Manual Visual Testing

Color Contrast Testing

1. Inspect element in DevTools → click color swatch → see contrast ratio 2. Use WAVE extension → contrast errors highlighted in red 3. Grayscale test: Apply filter: grayscale(100%) to <html> in DevTools — can you still distinguish all elements? 4. Color blindness simulation: Chrome DevTools → Rendering → Emulate vision deficiencies

Zoom and Reflow Testing

Text Spacing Bookmarklet

Save this as a bookmark and click it on any page to test text spacing compliance (1.4.12):

javascript:void(function(){var s=document.createElement('style');s.textContent='*{line-height:1.5em!important;letter-spacing:0.12em!important;word-spacing:0.16em!important}p{margin-bottom:2em!important}';document.head.appendChild(s)})()

Reduced Motion Testing

1. macOS: System Settings → Accessibility → Display → Reduce motion 2. Chrome DevTools: Rendering → Emulate CSS media feature prefers-reduced-motion: reduce 3. Check: Do animations stop or simplify? Does the page still work?

---

Testing Cheat Sheet

Quick Audit (30 Minutes)

Full Audit (2-3 Hours Per Page)

---

Accessibility Testing in Design Phase

Don't wait until code. Catch issues in design:

WCAG 2.2 Checklist — Organized by Audit Task

This checklist reorganizes WCAG 2.2 success criteria by what you're actually checking during an audit, rather than by WCAG principle number. Each section groups related criteria that you'd test together.

---

1. Text Alternatives and Media

Check all non-text content for appropriate alternatives.

Images (1.1.1 — A)

• [ ] Functional images (convey information) have descriptive alt text
• [ ] Decorative images have alt="" or are implemented as CSS backgrounds
• [ ] Linked images have alt text describing the destination
• [ ] Image buttons have alt text describing the action
• [ ] Complex images (charts, infographics) have extended descriptions in context or on a linked page
• [ ] Image map hotspots have appropriate alt text
• [ ] Images of text are not used when real text could achieve the same presentation (1.4.5 — AA)

Audio and Video

Embedded Content

• [ ] Frames and iframes have descriptive title attributes (1.1.1 — A)
• [ ] Embedded multimedia is identified via accessible text (1.1.1 — A)

---

2. Semantic Structure and Relationships

Check that content structure is programmatically determinable.

Headings (1.3.1 — A)

• [ ] Heading levels don't skip (h1 → h2 → h3, never h1 → h3)
• [ ] Page has exactly one <h1>
• [ ] Headings describe the content that follows
• [ ] Heading levels reflect content hierarchy, not visual styling
• [ ] Section headings are used to organize long content (2.4.10 — AAA)

Landmarks and Regions (1.3.1 — A, 1.3.6 — AAA)

• [ ] Page uses semantic landmarks: <header>, <nav>, <main>, <footer>, <aside>
• [ ] Multiple instances of the same landmark have unique labels (aria-label)
• [ ] ARIA landmark roles are used to enhance HTML where needed (1.3.6 — AAA)

Lists (1.3.1 — A)

• [ ] Related items use <ul>, <ol>, or <dl> — not styled <div>s
• [ ] Navigation menus use list markup

Tables (1.3.1 — A)

• [ ] Data tables use <th> for headers with scope attribute
• [ ] Complex tables use id/headers associations
• [ ] Table captions use <caption> element
• [ ] Layout tables (if any) do NOT use <th>, <caption>, or summary

Reading Order (1.3.2 — A)

• [ ] DOM order matches visual order
• [ ] CSS doesn't create a reading order that contradicts the DOM
• [ ] Content makes sense when linearized (single column)

Sensory Characteristics (1.3.3 — A)

• [ ] Instructions don't rely solely on shape, size, or position ("click the green button on the right")
• [ ] Instructions don't rely solely on sound ("a beep indicates success")

---

3. Color and Contrast

Text Contrast

Non-Text Contrast (1.4.11 — AA)

• [ ] UI components (buttons, inputs, dropdowns): ≥ 3:1 against adjacent colors
• [ ] Graphical objects conveying information (icons, chart segments): ≥ 3:1
• [ ] Focus indicators: ≥ 3:1 against background
• [ ] Component states (hover, active, selected): maintain ≥ 3:1

Color as Information (1.4.1 — A)

• [ ] Color is not the sole method of conveying information
• [ ] Links are distinguishable from body text by more than color alone (underline, or ≥ 3:1 contrast + hover/focus change)
• [ ] Form errors indicated by more than a red border (add icon, text, or pattern)
• [ ] Charts use patterns or labels in addition to color

---

4. Keyboard Access

Full Keyboard Support (2.1.1 — A)

• [ ] All interactive elements are reachable via Tab
• [ ] All interactive elements can be activated via Enter or Space
• [ ] Custom widgets support expected keyboard patterns (arrows for tabs/menus, Escape to close)
• [ ] No keyboard traps — user can always Tab away (2.1.2 — A)
• [ ] Character key shortcuts can be disabled or remapped (2.1.4 — A)

Focus Management

Focus Behavior

• [ ] Focus moves to modals when opened
• [ ] Focus is trapped within open modals (can't Tab to content behind)
• [ ] Focus returns to trigger element when modal closes
• [ ] Focus moves to new content when dynamically added (e.g., error summary)
• [ ] Focus is not moved unexpectedly

---

5. Pointer and Touch Input

Pointer Gestures (2.5.1 — A)

• [ ] Multipoint gestures (pinch, swipe) have single-pointer alternatives
• [ ] Path-based gestures (drag) have click/tap alternatives

Pointer Behavior

Target Size

---

6. Forms and Input

Labels and Instructions

• [ ] Every input has a programmatic label: <label for="..."> or aria-label (1.1.1, 1.3.1 — A)
• [ ] Related inputs grouped with <fieldset> and <legend> (1.3.1 — A)
• [ ] Required fields indicated in the label (not just by color or asterisk alone) (3.3.2 — A)
• [ ] Input purpose identified with autocomplete for personal data (1.3.5 — AA)
• [ ] Sufficient instructions and examples provided (3.3.2 — A)

Error Handling

Error Presentation

• [ ] Error messages identify which field has the error
• [ ] Error messages describe what's wrong and how to fix it
• [ ] Errors are announced to screen readers (via aria-live, aria-describedby, or focus management)
• [ ] Error summary at top of form links to each problematic field

New in 2.2

• [ ] Redundant entry: information is auto-populated or selectable — don't ask twice (3.3.7 — A)
• [ ] Authentication: no cognitive function tests without alternatives (3.3.8 — AA)

---

7. Navigation and Wayfinding

Page-Level

• [ ] Skip link to main content (2.4.1 — A)
• [ ] Descriptive page title: "[Page] — [Site]" (2.4.2 — A)
• [ ] <html lang="..."> set correctly (3.1.1 — A)
• [ ] Language changes within page marked with lang attribute (3.1.2 — AA)

Site-Level

• [ ] Multiple navigation methods: nav + search, or nav + sitemap (2.4.5 — AA)
• [ ] Navigation order consistent across pages (3.2.3 — AA)
• [ ] Same functionality labeled consistently across pages (3.2.4 — AA)
• [ ] Help mechanisms in consistent location (3.2.6 — A, new in 2.2)

Links

• [ ] Link text describes the destination (not "click here" or "read more") (2.4.4 — A)
• [ ] Links with identical text go to identical destinations (2.4.4 — A)
• [ ] Link text alone is sufficient to determine purpose (2.4.9 — AAA)

---

8. Time, Motion, and Interruptions

Time Limits (2.2.1 — A)

• [ ] Users can extend, adjust, or turn off time limits
• [ ] Users warned before timeout that could lose data (2.2.6 — AAA)
• [ ] Re-authentication preserves user data (2.2.5 — AAA)

Motion and Animation

• [ ] Auto-playing content (carousels, animations) can be paused/stopped after 5 seconds (2.2.2 — A)
• [ ] No content flashes more than 3 times per second (2.3.1 — A)
• [ ] prefers-reduced-motion media query respected (2.3.3 — AAA)
• [ ] Auto-updating content (feeds, tickers) can be paused (2.2.2 — A)

Audio

• [ ] Auto-playing audio (>3 seconds) can be paused, stopped, or volume adjusted (1.4.2 — A)

---

9. Text and Content Presentation

Resizing and Reflow

Text Presentation (1.4.8 — AAA)

• [ ] Line length ≤ 80 characters
• [ ] Text not fully justified (no left + right alignment)
• [ ] Line spacing ≥ 1.5× font size
• [ ] Paragraph spacing ≥ 1.5× line spacing
• [ ] Foreground and background colors are defined/inheritable

Readability

• [ ] Content written at appropriate reading level (3.1.5 — AAA: ~9th grade)
• [ ] Unusual words defined (3.1.3 — AAA)
• [ ] Abbreviations expanded on first use (3.1.4 — AAA)

---

10. Predictability and Behavior

No Surprise Changes

• [ ] Receiving focus doesn't trigger page changes (3.2.1 — A)
• [ ] Changing an input value doesn't trigger unexpected changes (3.2.2 — A)
• [ ] Major changes only happen on user request (3.2.5 — AAA)

Hover and Focus Content (1.4.13 — AA)

• [ ] Content appearing on hover/focus is dismissible (Esc key)
• [ ] User can hover over the new content without it disappearing
• [ ] Content persists until focus moves, user dismisses it, or it's no longer relevant

---

11. ARIA and Custom Components (4.1.2 — A)

General ARIA Rules

1. Don't use ARIA if native HTML works 2. Don't change native semantics unless necessary 3. All interactive ARIA controls must be keyboard operable 4. Don't use role="presentation" or aria-hidden="true" on focusable elements 5. All interactive elements must have accessible names

Common ARIA Patterns

Status Messages (4.1.3 — AA)

• [ ] Success messages announced via aria-live="polite" or role="status"
• [ ] Error messages announced via aria-live="assertive" or role="alert"
• [ ] Loading states announced (e.g., aria-busy="true" on region, or live region update)
• [ ] Search result counts announced

Accessibility Audit Report

Audit Overview

• Product/Page: [What was audited]
• URL(s): [Specific URLs tested]
• Date: [Audit date]
• Auditor: [Name]
• Target conformance: WCAG 2.2 Level [A / AA / AAA]
• Testing methods: [Automated scan, keyboard testing, screen reader testing, visual review]
• Tools used: [axe DevTools, WAVE, VoiceOver, NVDA, Chrome DevTools, etc.]
• Browsers/devices: [Chrome on macOS, Safari on iOS, etc.]

---

Executive Summary

3-5 bullet points that a stakeholder can read in 30 seconds.

• Overall conformance: [Passes / Does not pass] WCAG 2.2 Level [AA]
• Total issues found: [#] ([#] Critical, [#] High, [#] Moderate, [#] Low)
• Top finding: [Most impactful issue — one sentence]
• Biggest quick win: [Easiest high-impact fix — one sentence]
• Recommendation: [Overall next step]

---

Score Summary

By Severity

By WCAG Principle

Automated Tool Score

---

Findings

Finding 1: [Issue title]

Severity: Critical / High / Moderate / Low WCAG Criterion: [Number] — [Name] (Level [A/AA/AAA]) Principle: Perceivable / Operable / Understandable / Robust Location: [Page, component, or element where the issue occurs] Affects: [Screen reader users / Keyboard users / Low vision users / Cognitive disabilities / All users]

Description: [What the issue is and why it matters]

Steps to reproduce: 1. [Step] 2. [Step] 3. [Observe: description of the problem]

Current code:

[Code showing the issue]

Recommended fix:

[Code showing the fix]

Effort: Small / Medium / Large

---

Finding 2: [Issue title]

Severity: Critical / High / Moderate / Low WCAG Criterion: [Number] — [Name] (Level [A/AA/AAA]) Principle: Perceivable / Operable / Understandable / Robust Location: [Page, component, or element] Affects: [User groups]

Description: [What and why]

Steps to reproduce: 1. [Step]

Current code:

[Code]

Recommended fix:

[Code]

Effort: Small / Medium / Large

---

Finding 3: [Issue title]

[Same structure as above]

---

Prioritized Remediation Plan

Tier definitions:

• Tier 1: Fix before next release — Critical/High severity or Level A violations
• Tier 2: Fix within current quarter — Moderate severity or Level AA violations
• Tier 3: Add to backlog — Low severity or Level AAA aspirational improvements

---

What Passed

Highlight what's working well. This encourages teams and identifies patterns to replicate.

• [Positive finding 1 — e.g., "All form inputs have programmatic labels"]
• [Positive finding 2 — e.g., "Keyboard navigation order is logical throughout"]
• [Positive finding 3 — e.g., "Error messages are descriptive and linked to fields"]
• [Positive finding 4 — e.g., "Skip navigation is present and functional"]

---

Testing Details

Pages/Flows Tested

Keyboard Testing Results

Screen Reader Testing Results

---

Recommendations for Ongoing Compliance

• [ ] Add automated testing to CI/CD — Use axe-core in Playwright/Cypress/Jest to prevent regressions
• [ ] Include accessibility in design reviews — Check contrast, focus states, and heading hierarchy in Figma
• [ ] Include accessibility in code reviews — Use the Quick Audit Checklist (see SKILL.md)
• [ ] Test with screen reader monthly — Assign rotating responsibility
• [ ] Re-audit after fixes — Verify Tier 1 fixes before release
• [ ] Schedule full re-audit — [Recommended date, typically quarterly]

---

Appendix

Tools Used

• [Tool 1]: [Version, settings]
• [Tool 2]: [Version, settings]

Standards Reference

• WCAG 2.2
• WebAIM WCAG Checklist
• ARIA Authoring Practices

Accessibility Quick Checklist

Page/Component: [What you're checking] Date: [Date] Checker: [Name]

Use this during sprint reviews, PR reviews, or quick spot-checks. Each item maps to a WCAG criterion.

---

Structure and Semantics

• [ ] Page has <html lang="..."> — (3.1.1 A)
• [ ] Page has one <h1>, headings don't skip levels — (1.3.1 A)
• [ ] Landmarks present: <header>, <nav>, <main>, <footer> — (1.3.1 A)
• [ ] Skip link present and functional — (2.4.1 A)
• [ ] Page has descriptive <title> — (2.4.2 A)
• [ ] Lists use <ul>/<ol>, not styled <div>s — (1.3.1 A)
• [ ] Data tables use <th> with scope — (1.3.1 A)

Images

• [ ] Functional images have descriptive alt — (1.1.1 A)
• [ ] Decorative images have alt="" — (1.1.1 A)
• [ ] Complex images have extended description — (1.1.1 A)

Forms

• [ ] Every input has a <label> — (1.3.1 A)
• [ ] Required fields indicated (not by color alone) — (3.3.2 A)
• [ ] Errors identify the field + describe the fix — (3.3.1 A, 3.3.3 AA)
• [ ] autocomplete on personal data fields — (1.3.5 AA)
• [ ] No redundant entry in single-session flows — (3.3.7 A)

Keyboard

• [ ] All interactive elements reachable via Tab — (2.1.1 A)
• [ ] Focus indicator visible on all elements — (2.4.7 AA)
• [ ] Focus order matches visual order — (2.4.3 A)
• [ ] No keyboard traps — (2.1.2 A)
• [ ] Modals trap focus, close on Esc, return focus — (2.1.2 A, 4.1.2 A)
• [ ] Focused elements not hidden behind sticky content — (2.4.11 AA)

Color and Contrast

• [ ] Text contrast ≥ 4.5:1 (≥ 3:1 large text) — (1.4.3 AA)
• [ ] UI component contrast ≥ 3:1 — (1.4.11 AA)
• [ ] Color not sole method of conveying info — (1.4.1 A)

Interactive Elements

• [ ] Links have descriptive text (not "click here") — (2.4.4 A)
• [ ] Buttons have accessible names — (4.1.2 A)
• [ ] Touch targets ≥ 24×24px — (2.5.8 AA)
• [ ] Drag operations have non-drag alternatives — (2.5.7 AA)
• [ ] Custom components have correct ARIA — (4.1.2 A)

Dynamic Content

• [ ] Status messages announced via aria-live — (4.1.3 AA)
• [ ] Loading states communicated — (4.1.3 AA)
• [ ] Hover/focus content dismissible + hoverable — (1.4.13 AA)

Responsive and Visual

• [ ] Content readable at 200% zoom — (1.4.4 AA)
• [ ] No horizontal scroll at 320px width — (1.4.10 AA)
• [ ] Layout survives text spacing changes — (1.4.12 AA)

Media

• [ ] Videos have captions — (1.2.2 A)
• [ ] Audio-only has transcript — (1.2.1 A)
• [ ] Auto-playing media can be paused — (1.4.2 A)
• [ ] No content flashes > 3 times/second — (2.3.1 A)

Authentication (2.2)

• [ ] No CAPTCHAs or puzzles without alternatives — (3.3.8 AA)
• [ ] Help in consistent location across pages — (3.2.6 A)

---

Results

Issues found: [#] Critical/High: [List] Action items: [What needs to happen next]