Accessibility Tester

Level A (Minimum):
  Must fix - basic barriers that completely block access.
  Examples: images without alt text, no keyboard access, auto-playing audio.

Level AA (Standard Target):
  Should fix - significant barriers for many users.
  Examples: insufficient color contrast, missing form labels, no skip navigation.
  This is the legal standard in most regulations (ADA, EN 301 549, EAA).

Level AAA (Enhanced):
  Nice to have - provides the best experience but not always feasible.
  Examples: sign language for video, extended audio descriptions.
  Typically targeted for specific content, not entire sites.

Criteria    | Level | What It Means                          | Common Failures
------------|-------|----------------------------------------|---------------------------
1.1.1       | A     | Non-text content has text alternative  | Images missing alt text
1.3.1       | A     | Info and structure conveyed in markup   | Tables without headers
1.4.3       | AA    | Color contrast ratio >= 4.5:1 (text)   | Light gray text on white
1.4.11      | AA    | Non-text contrast >= 3:1               | Low contrast icons/borders
2.1.1       | A     | All functionality via keyboard          | Mouse-only interactions
2.1.2       | A     | No keyboard traps                      | Modal without Escape key
2.4.1       | A     | Skip navigation mechanism               | No skip-to-content link
2.4.4       | A     | Link purpose clear from text           | "Click here" links
2.4.7       | AA    | Visible focus indicator                | Removed outline styles
3.1.1       | A     | Page language specified                | Missing lang attribute
3.3.1       | A     | Input errors identified and described  | Form errors without message
3.3.2       | A     | Labels or instructions for input       | Placeholder-only inputs
4.1.2       | A     | Name, role, value for UI components    | Custom widgets without ARIA

// Playwright + axe-core for automated accessibility scanning
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test.describe('Accessibility', () => {
  test('homepage has no critical a11y violations', async ({ page }) => {
    await page.goto('/');

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
      .exclude('#third-party-widget')  // Exclude content you don't control
      .analyze();

    // Report violations with details
    const violations = results.violations;
    if (violations.length > 0) {
      const violationReport = violations.map(v => ({
        id: v.id,
        impact: v.impact,
        description: v.description,
        nodes: v.nodes.length,
        help: v.helpUrl,
      }));
      console.table(violationReport);
    }

    expect(violations).toEqual([]);
  });

  test('login form is accessible', async ({ page }) => {
    await page.goto('/login');

    const results = await new AxeBuilder({ page })
      .include('#login-form')   // Scope to specific component
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();

    expect(results.violations).toEqual([]);
  });

  // Test multiple pages systematically
  const pages = ['/', '/about', '/products', '/contact', '/login'];

  for (const pagePath of pages) {
    test(`${pagePath} has no a11y violations`, async ({ page }) => {
      await page.goto(pagePath);
      // Wait for dynamic content to load
      await page.waitForLoadState('networkidle');

      const results = await new AxeBuilder({ page })
        .withTags(['wcag2a', 'wcag2aa'])
        .analyze();

      expect(results.violations).toEqual([]);
    });
  }
});

import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

describe('Button component accessibility', () => {
  test('primary button has no violations', async () => {
    const { container } = render(
      <Button variant="primary" onClick={() => {}}>
        Save Changes
      </Button>
    );

    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  test('icon-only button requires aria-label', async () => {
    const { container } = render(
      <Button variant="icon" aria-label="Close dialog" onClick={() => {}}>
        <CloseIcon />
      </Button>
    );

    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

# .github/workflows/a11y.yml
name: Accessibility Audit

on: [pull_request]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }

      - run: npm ci && npm run build
      - run: npm run start &
      - run: npx wait-on [reference URL]

      - name: Run Lighthouse
        uses: treosh/lighthouse-ci-action@v12
        with:
          urls: |
            [reference URL]
            [reference URL]
            [reference URL]
          configPath: .lighthouserc.json
          uploadArtifacts: true

// .lighthouserc.json
{
  "ci": {
    "assert": {
      "assertions": {
        "categories:accessibility": ["error", { "minScore": 0.9 }],
        "color-contrast": "error",
        "image-alt": "error",
        "label": "error",
        "link-name": "error",
        "button-name": "error",
        "html-has-lang": "error",
        "document-title": "error"
      }
    }
  }
}

Test every interactive element with keyboard only (no mouse):

Navigation:
[ ] Tab moves focus forward through all interactive elements
[ ] Shift+Tab moves focus backward
[ ] Focus order matches visual order (logical reading sequence)
[ ] No keyboard traps (can always Tab away from any element)
[ ] Skip navigation link present and working

Focus Visibility:
[ ] Focus indicator visible on every interactive element
[ ] Focus indicator has >= 3:1 contrast against adjacent colors
[ ] Focus indicator visible in both light and dark modes
[ ] Custom focus styles do not reduce visibility

Interactive Elements:
[ ] Buttons activated with Enter and Space
[ ] Links activated with Enter
[ ] Checkboxes toggled with Space
[ ] Radio buttons navigated with Arrow keys
[ ] Select/dropdown opened with Space or Enter, navigated with Arrow keys
[ ] Tabs navigated with Arrow keys (not Tab key between tabs)

Modals and Dialogs:
[ ] Focus moves to modal when opened
[ ] Tab is trapped within modal (focus does not escape behind it)
[ ] Escape key closes modal
[ ] Focus returns to trigger element when modal closes

Custom Components:
[ ] Custom dropdowns keyboard-accessible
[ ] Drag-and-drop has keyboard alternative
[ ] Sliders adjustable with Arrow keys
[ ] Date pickers navigable with keyboard

// Playwright keyboard navigation test
test('modal traps focus correctly', async ({ page }) => {
  await page.goto('/dashboard');

  // Open modal
  await page.getByRole('button', { name: 'Create Project' }).click();
  const modal = page.getByRole('dialog');
  await expect(modal).toBeVisible();

  // First focusable element should receive focus
  const firstInput = modal.getByLabel('Project Name');
  await expect(firstInput).toBeFocused();

  // Tab through all elements in modal
  await page.keyboard.press('Tab'); // -> Description field
  await page.keyboard.press('Tab'); // -> Cancel button
  await page.keyboard.press('Tab'); // -> Create button
  await page.keyboard.press('Tab'); // -> Should wrap to Project Name

  // Verify focus wrapped back to first element (trapped in modal)
  await expect(firstInput).toBeFocused();

  // Escape closes modal
  await page.keyboard.press('Escape');
  await expect(modal).toBeHidden();

  // Focus returns to trigger button
  await expect(
    page.getByRole('button', { name: 'Create Project' })
  ).toBeFocused();
});

// Test tab order matches visual order
test('form tab order is logical', async ({ page }) => {
  await page.goto('/signup');

  const expectedOrder = [
    'First Name',
    'Last Name',
    'Email',
    'Password',
    'Confirm Password',
    'I agree to terms',
    'Create Account',
  ];

  for (const label of expectedOrder) {
    await page.keyboard.press('Tab');
    const focused = page.locator(':focus');
    const name = await focused.getAttribute('aria-label')
      || await focused.innerText()
      || await page.evaluate(() => {
          const el = document.activeElement;
          const label = el?.labels?.[0];
          return label?.textContent || el?.textContent;
        });
    expect(name).toContain(label);
  }
});

Setup:
  macOS:  VoiceOver (built-in, Cmd+F5 to toggle)
  Windows: NVDA (free, open source) or JAWS (commercial)
  Linux:  Orca (built-in on GNOME)
  Mobile: VoiceOver (iOS), TalkBack (Android)

Basic VoiceOver commands (macOS + Safari):
  VO = Control + Option
  VO + Right Arrow:  Move to next element
  VO + Left Arrow:   Move to previous element
  VO + Space:        Activate current element
  VO + U:            Open rotor (headings, links, landmarks)
  VO + Cmd + H:      Next heading
  VO + Cmd + L:      Next link

Basic NVDA commands (Windows + Chrome/Firefox):
  Insert + Down Arrow: Read from current position
  H:                   Next heading
  Tab:                 Next form control
  D:                   Next landmark
  K:                   Next link
  Insert + F7:         Elements list (links, headings, landmarks)

Page Structure:
[ ] Page title is descriptive and unique
[ ] Headings form a logical hierarchy (h1 > h2 > h3, no skips)
[ ] Landmark regions present (main, nav, header, footer, search)
[ ] Reading order makes sense when linearized

Images and Media:
[ ] Informative images have descriptive alt text
[ ] Decorative images have alt="" (empty alt, not missing alt)
[ ] Complex images (charts, diagrams) have extended descriptions
[ ] Videos have captions and audio descriptions

Forms:
[ ] Every input has an associated label (visible label, not placeholder only)
[ ] Required fields indicated programmatically (aria-required)
[ ] Error messages associated with their fields (aria-describedby)
[ ] Form instructions read before the form, not after
[ ] Autocomplete attributes present for common fields

Dynamic Content:
[ ] Live regions announce updates (aria-live="polite" or "assertive")
[ ] Loading states announced to screen reader users
[ ] Toast/notification messages are read aloud
[ ] Route changes in SPAs announce new page context

WCAG AA Requirements:
  Normal text (<24px / <18.7px bold): 4.5:1 contrast ratio
  Large text (>=24px / >=18.7px bold): 3:1 contrast ratio
  UI components and graphical objects:  3:1 contrast ratio

  Focus indicators: 3:1 against adjacent colors

Checking tools:
  - Chrome DevTools: Inspect element → color picker shows ratio
  - Lighthouse: Automated color contrast audit
  - axe DevTools browser extension
  - WebAIM Contrast Checker (webaim.org/resources/contrastchecker)

Common failures:
  Light gray text (#999) on white (#FFF): 2.85:1 (FAIL)
  Fixed: Use #767676 on white: 4.54:1 (PASS AA)

  Placeholder text (#AAA) on white (#FFF): 2.32:1 (FAIL)
  Fixed: Use #757575 on white: 4.60:1 (PASS AA)
  ALSO: Never use placeholder as the only label

Test: Can you understand the UI without seeing colors?

Common failures:
  - Red/green to indicate valid/invalid (add icons or text)
  - Color-coded status without labels (add text labels)
  - Charts using only color to distinguish series (add patterns)
  - Links distinguished only by color (add underline)

Automated check:
  - Use browser grayscale filter to review pages:
    filter: grayscale(100%)
  - If any information is lost, color is being used as sole indicator

# GitHub Actions: Block PR merge on a11y violations
name: A11y Gate
on: [pull_request]

jobs:
  a11y-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci && npm run build
      - run: npm run start &
      - run: npx wait-on [reference URL]
      - name: Run axe accessibility tests
        run: npx playwright test tests/a11y/
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: a11y-results
          path: playwright-report/

Automated Scans:
[ ] axe-core scans pass with zero violations (wcag2a + wcag2aa)
[ ] Lighthouse accessibility score >= 90
[ ] Component-level tests with jest-axe pass
[ ] CI/CD gate blocks PRs with new violations

Keyboard Testing:
[ ] All interactive elements reachable via Tab
[ ] Focus indicators visible on all elements
[ ] No keyboard traps
[ ] Modal focus management correct (trap, return, escape)
[ ] Skip navigation link functional

Screen Reader Testing:
[ ] Page structure (headings, landmarks) makes sense
[ ] Images have appropriate alt text
[ ] Forms are labeled and errors are announced
[ ] Dynamic content updates are announced (aria-live)
[ ] SPA route changes announce new content

Visual Testing:
[ ] Color contrast meets AA ratios (4.5:1 text, 3:1 components)
[ ] Information not conveyed by color alone
[ ] Content readable at 200% zoom
[ ] Responsive layout works with text resizing
[ ] Animations respect prefers-reduced-motion

# Accessibility Tester Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]