Accessibility A11y Enhanced

# Accessibility A11y Enhanced Skill

You are an expert accessibility engineer specializing in WCAG compliance and inclusive web design. When asked to test or improve accessibility, follow these comprehensive instructions.

## Core Principles (POUR)

1. **Perceivable** -- Information must be presentable to users in ways they can perceive.
2. **Operable** -- User interface components must be operable by all users.
3. **Understandable** -- Information and operation must be understandable.
4. **Robust** -- Content must be robust enough to work with assistive technologies.

## WCAG 2.1 Compliance Levels

```
Level A (Minimum)
- Basic accessibility features
- Essential for some users
- Examples: Alt text, keyboard access, labels

Level AA (Standard)
- Recommended baseline for most sites
- Addresses major barriers
- Examples: Color contrast 4.5:1, focus indicators, skip links

Level AAA (Enhanced)
- Highest accessibility standard
- Not always achievable for all content
- Examples: Color contrast 7:1, sign language, extended descriptions
```

## Setting Up Automated Testing

### With Playwright and axe-core

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});
```

```bash
npm install --save-dev @axe-core/playwright
```

```typescript
// tests/accessibility.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test.describe('Accessibility tests', () => {
  test('should not have any automatically detectable accessibility issues', async ({ page }) => {
    await page.goto('/');

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

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

  test('should have accessible homepage', async ({ page }) => {
    await page.goto('/');

    const results = await new AxeBuilder({ page })
      .exclude('#third-party-widget') // Exclude third-party content
      .analyze();

    // Log violations for debugging
    if (results.violations.length > 0) {
      console.log('Accessibility violations:', JSON.stringify(results.violations, null, 2));
    }

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

  test('should have accessible forms', async ({ page }) => {
    await page.goto('/contact');

    const results = await new AxeBuilder({ page })
      .include('form') // Test only forms
      .analyze();

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

  test('should meet specific WCAG rules', async ({ page }) => {
    await page.goto('/');

    const results = await new AxeBuilder({ page })
      .withRules(['color-contrast', 'image-alt', 'label', 'aria-required-attr'])
      .analyze();

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

### With Cypress and axe-core

```typescript
// cypress/support/commands.ts
import 'cypress-axe';

Cypress.Commands.add('checkA11y', (context?: string, options?: any) => {
  cy.injectAxe();
  cy.checkA11y(context, options, (violations) => {
    if (violations.length) {
      cy.task('log', violations);
    }
  });
});
```

```typescript
// cypress/e2e/accessibility.cy.ts
describe('Accessibility', () => {
  beforeEach(() => {
    cy.visit('/');
    cy.injectAxe();
  });

  it('should have no accessibility violations on homepage', () => {
    cy.checkA11y();
  });

  it('should have accessible navigation', () => {
    cy.checkA11y('nav');
  });

  it('should meet WCAG AA color contrast', () => {
    cy.checkA11y(null, {
      rules: {
        'color-contrast': { enabled: true },
      },
    });
  });
});
```

## Manual Accessibility Testing

### 1. Keyboard Navigation Tests

```typescript
test.describe('Keyboard navigation', () => {
  test('should navigate through interactive elements with Tab', async ({ page }) => {
    await page.goto('/');

    // Start at the first focusable element
    await page.keyboard.press('Tab');

    const firstFocusedElement = await page.evaluate(() => document.activeElement?.tagName);
    expect(['A', 'BUTTON', 'INPUT']).toContain(firstFocusedElement);

    // Tab through all interactive elements
    for (let i = 0; i < 5; i++) {
      await page.keyboard.press('Tab');
      const focused = await page.evaluate(() => {
        const el = document.activeElement;
        return {
          tag: el?.tagName,
          visible: el ? window.getComputedStyle(el).display !== 'none' : false,
        };
      });

      expect(focused.visible).toBe(true);
    }
  });

  test('should submit form with Enter key', async ({ page }) => {
    await page.goto('/contact');

    await page.fill('#name', 'Test User');
    await page.fill('#email', 'test@example.com');
    await page.fill('#message', 'Test message');

    // Focus on submit button and press Enter
    await page.focus('button[type="submit"]');
    await page.keyboard.press('Enter');

    await expect(page.getByText('Message sent')).toBeVisible();
  });

  test('should close modal with Escape key', async ({ page }) => {
    await page.goto('/');

    await page.click('button[aria-label="Open modal"]');
    await expect(page.getByRole('dialog')).toBeVisible();

    await page.keyboard.press('Escape');
    await expect(page.getByRole('dialog')).not.toBeVisible();
  });

  test('should skip to main content with skip link', async ({ page }) => {
    await page.goto('/');

    // Tab to skip link
    await page.keyboard.press('Tab');

    const skipLink = page.getByText('Skip to main content');
    await expect(skipLink).toBeFocused();

    // Activate skip link
    await page.keyboard.press('Enter');

    // Main content should now be focused
    const mainContent = page.locator('main');
    await expect(mainContent).toBeFocused();
  });
});
```

### 2. Focus Management Tests

```typescript
test.describe('Focus management', () => {
  test('should h