// tests/accessibility.spec.ts
import { test, expect } from '@playwright/test';
import { injectAxe, checkA11y, getViolations } from 'axe-playwright';

test.describe('Accessibility Audit', () => {
  test('should not have accessibility violations on critical paths', async ({ page }) => {
    await page.goto('/');
    await injectAxe(page);
    
    // Configure axe to ignore specific known issues or third-party widgets
    const options = {
      runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'],
      },
    };

    const violations = await getViolations(page, null, options);
    
    // Fail the test if critical violations are found
    expect(violations.length).toBe(0);
    
    if (violations.length > 0) {
      console.error('Accessibility Violations:', JSON.stringify(violations, null, 2));
    }
  });
});

// hooks/useFocusManagement.ts
import { useEffect, useRef, useCallback } from 'react';
import { createFocusTrap, FocusTrap } from 'focus-trap';

export function useFocusTrap(isActive: boolean) {
  const containerRef = useRef<HTMLDivElement>(null);
  const focusTrapRef = useRef<FocusTrap | null>(null);

  const setupFocusTrap = useCallback(() => {
    if (containerRef.current && isActive) {
      focusTrapRef.current = createFocusTrap(containerRef.current, {
        onDeactivate: () => {
          // Return focus to the trigger element
          const trigger = document.getElementById('modal-trigger');
          trigger?.focus();
        },
        fallbackFocus: containerRef.current,
      });
      focusTrapRef.current.activate();
    }
  }, [isActive]);

  useEffect(() => {
    if (isActive) {
      setupFocusTrap();
    } else {
      focusTrapRef.current?.deactivate();
    }
  }, [isActive, setupFocusTrap]);

  return containerRef;
}

// Usage in Modal Component
export const Modal = ({ isOpen, onClose, children }: ModalProps) => {
  const trapRef = useFocusTrap(isOpen);
  
  if (!isOpen) return null;

  return (
    <div role="dialog" aria-modal="true" aria-labelledby="modal-title" ref={trapRef}>
      <h2 id="modal-title">Settings</h2>
      {children}
      <button onClick={on

Close}>Close</button> </div> ); };

**Rationale:** `tabindex="-1"` is required for programmatic focus but excludes elements from the tab order. `tabindex="0"` includes elements in the natural tab order. Misusing these attributes is a leading cause of audit failures. The hook ensures focus is trapped within the modal and restored correctly upon closure.

### Step 3: Dynamic Content and Live Regions

Dynamic updates must be announced to screen readers without disrupting the user's current task.

**Implementation:** Use `aria-live` regions for asynchronous updates.

```typescript
// components/NotificationToast.tsx
export const NotificationToast = ({ message, type }: ToastProps) => {
  return (
    <div 
      role="alert" 
      aria-live="assertive" 
      className={`toast toast-${type}`}
    >
      {message}
    </div>
  );
};

Audit Check: Verify that role="alert" or aria-live="polite" is used appropriately. assertive interrupts the user; use only for critical errors. polite queues the announcement.

Step 4: Color Contrast and Visual Verification

Automated tools check contrast ratios, but they often miss gradients, overlays, and dynamic styling.

Implementation: Integrate a contrast checker into the design system review process.

// utils/contrast.ts
function luminance(r: number, g: number, b: number): number {
  const [rs, gs, bs] = [r, g, b].map((c) => {
    const srgb = c / 255;
    return srgb <= 0.03928 ? srgb / 12.92 : Math.pow((srgb + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
}

export function contrastRatio(color1: string, color2: string): number {
  // Parse hex/rgb to luminance and calculate ratio
  // Implementation omitted for brevity; use libraries like 'wcag-contrast'
  return 0; 
}

Audit Action: Manually verify contrast ratios for all interactive states: :hover, :focus, :active, disabled, and visited. Check text over images and gradients. WCAG 2.2 requires a minimum ratio of 4.5:1 for normal text and 3:1 for large text.

Pitfall Guide

1. ARIA Misuse and Over-Engineering

Mistake: Adding role="button" to a <div> with an onClick handler but no keyboard support. Explanation: ARIA does not add functionality; it only exposes semantics. If you use role="button", you must implement onKeyDown for Enter and Space keys. Best Practice: Use semantic HTML elements (<button>, <a>, <nav>) whenever possible. ARIA is a last resort for complex widgets not covered by HTML.

2. Ignoring DOM Order vs. Visual Order

Mistake: Using CSS Grid or Flexbox to visually reorder elements, causing the reading order to mismatch the visual layout. Explanation: Screen readers follow the DOM order. If the visual layout places a "Submit" button before the form fields, but the DOM has the button last, screen reader users encounter the button out of context. Best Practice: Ensure the DOM source order matches the logical reading order. Avoid order property in Flexbox/Grid for reordering content that impacts meaning.

3. Focus Loss on Dynamic Updates

Mistake: Opening a modal or loading a new route without moving focus to the new content. Explanation: Users relying on keyboards or screen readers may be left "stranded" with focus on a hidden element or the previous page context. Best Practice: Move focus to the container of new content or the first interactive element. Use tabindex="-1" to make non-interactive containers focusable if necessary.

4. Inaccessible Form Error Handling

Mistake: Displaying error messages visually without linking them to the input via aria-describedby. Explanation: Screen reader users will not hear the error message unless it is programmatically associated with the input. Best Practice: Use aria-describedby pointing to the error message ID. Ensure errors are announced immediately upon validation failure.

5. Touch Target Size Violations (WCAG 2.2)

Mistake: Interactive elements smaller than 24x24 CSS pixels. Explanation: WCAG 2.2 introduced SC 2.5.8 Target Size. Small targets are difficult for users with motor impairments. Best Practice: Ensure all interactive elements have a minimum target size of 24x24 pixels. Use padding to increase clickable area without changing visual size.

6. Hidden Content Accessibility

Mistake: Hiding content with display: none but leaving it accessible to screen readers, or vice versa. Explanation: display: none removes elements from the accessibility tree. visibility: hidden does the same. However, off-screen positioning techniques must be used carefully to hide content visually while keeping it accessible for screen readers. Best Practice: Use the .sr-only utility class for visually hidden but accessible content. Use aria-hidden="true" for decorative elements or duplicated content.

7. Single Screen Reader Testing

Mistake: Auditing only with VoiceOver on macOS. Explanation: Screen readers behave differently across platforms. VoiceOver, NVDA, and JAWS have distinct rendering engines and interaction models. Best Practice: Test with at least two screen readers: one on Windows (NVDA or JAWS) and one on macOS/iOS (VoiceOver). Verify behavior in both desktop and mobile modes.

Production Bundle

Action Checklist

• Run Automated Scan: Execute axe-core on all critical user journeys in CI/CD. Block merges on critical violations.
• Verify Keyboard Navigation: Navigate the entire application using only Tab, Shift+Tab, Enter, Space, Escape, and Arrow keys.
• Check Focus Management: Ensure focus moves logically on route changes, modal opens/closes, and dynamic content updates.
• Validate ARIA Attributes: Review all ARIA usage. Ensure no role is used without corresponding keyboard handlers. Check aria-live regions for correct politeness settings.
• Test Contrast Ratios: Manually verify contrast for all states, including hover, focus, disabled, and text over images/gradients.
• Screen Reader Audit: Test with NVDA and VoiceOver. Verify that all interactive elements are announced correctly and live regions function.
• Review Target Sizes: Confirm all interactive elements meet the 24x24 pixel minimum target size requirement.
• Error Handling Check: Verify form errors are announced and associated with inputs via aria-describedby.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Startup MVP	Automated Scan + Manual Keyboard Check	Speed is critical; focus on critical paths. Manual screen reader testing can be deferred to v1.	Low
Enterprise Legacy App	Hybrid Audit with Component Triage	High risk of technical debt. Prioritize high-traffic pages. Use automated tools to identify low-hanging fruit.	Medium
Design System	Component-Level Audit + ESLint Rules	Ensure accessibility is baked into reusable components. Prevents propagation of issues to consuming apps.	High (Upfront), Low (Long-term)
Regulatory Compliance	Full Manual Audit + User Testing	Legal requirements demand comprehensive validation. Automated tools are insufficient for defense.	High

Configuration Template

Playwright Configuration with axe-core:

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

ESLint Configuration for Accessibility:

// .eslintrc.json
{
  "extends": [
    "plugin:jsx-a11y/recommended"
  ],
  "plugins": [
    "jsx-a11y"
  ],
  "rules": {
    "jsx-a11y/alt-text": "error",
    "jsx-a11y/anchor-has-content": "error",
    "jsx-a11y/click-events-have-key-events": "warn",
    "jsx-a11y/no-static-element-interactions": "warn",
    "jsx-a11y/role-has-required-aria-props": "error",
    "jsx-a11y/aria-props": "error",
    "jsx-a11y/aria-proptypes": "error"
  }
}

Quick Start Guide

1. Install Tools: Run npm install axe-core axe-playwright eslint-plugin-jsx-a11y --save-dev.
2. Configure CI: Add the axe-playwright test script to your pipeline. Configure it to fail on critical violations.
3. Add ESLint: Update .eslintrc to include jsx-a11y rules. Run npx eslint . --fix to resolve auto-fixable issues.
4. Run Manual Check: Perform a keyboard-only navigation test on your homepage. Fix focus order issues immediately.
5. Document: Create an ACCESSIBILITY.md file documenting known issues, exemptions, and the audit process for the team.

This guide provides the technical foundation for conducting effective web accessibility audits. By combining automated enforcement with rigorous manual verification, frontend teams can ensure applications are inclusive, compliant, and resilient against legal and usability risks. Accessibility is not a feature; it is a quality attribute that must be engineered into every layer of the application.