accessibility-testing

axe-core integration, WCAG 2.2 AA checklist, keyboard navigation testing, screen reader testing, and ARIA pattern validation.

422 stars

byvibeeval

View on GitHub Installation ↓

Best use case

accessibility-testing is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

axe-core integration, WCAG 2.2 AA checklist, keyboard navigation testing, screen reader testing, and ARIA pattern validation.

Teams using accessibility-testing should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/accessibility-testing/SKILL.md --create-dirs "https://raw.githubusercontent.com/vibeeval/vibecosystem/main/skills/accessibility-testing/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/accessibility-testing/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How accessibility-testing Compares

Feature / Agent	accessibility-testing	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

axe-core integration, WCAG 2.2 AA checklist, keyboard navigation testing, screen reader testing, and ARIA pattern validation.

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# Accessibility Testing

## axe-core Setup

### jest-axe (unit / component tests)
```typescript
import { axe, toHaveNoViolations } from 'jest-axe'
import { render } from '@testing-library/react'
expect.extend(toHaveNoViolations)

test('LoginForm has no a11y violations', async () => {
  const { container } = render(<LoginForm />)
  const results = await axe(container)
  expect(results).toHaveNoViolations()
})
```

### playwright-axe (e2e)
```typescript
import { test, expect } from '@playwright/test'
import AxeBuilder from '@axe-core/playwright'

test('homepage passes axe audit', async ({ page }) => {
  await page.goto('/')
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
    .analyze()
  expect(results.violations).toEqual([])
})
```

### cypress-axe
```javascript
// cypress/support/e2e.js
import 'cypress-axe'

// in test
cy.visit('/')
cy.injectAxe()
cy.checkA11y(null, {
  runOnly: { type: 'tag', values: ['wcag2aa'] },
})
```

## WCAG 2.2 AA Checklist — Top 20 Violations

| # | Criterion | Check |
|---|-----------|-------|
| 1 | Images have alt text | `<img alt="description">` or `alt=""` for decorative |
| 2 | Form inputs have labels | `<label for>` or `aria-label` or `aria-labelledby` |
| 3 | Color contrast ≥ 4.5:1 | Normal text; 3:1 for large text (18pt or 14pt bold) |
| 4 | Heading hierarchy | h1 → h2 → h3, no skipping levels |
| 5 | Keyboard focusable | All interactive elements reachable via Tab |
| 6 | Focus visible | `:focus` outline never `outline: none` without replacement |
| 7 | No keyboard trap | Tab can always exit modals, dropdowns, widgets |
| 8 | Skip navigation link | First focusable element: "Skip to main content" |
| 9 | Page has `<title>` | Unique, descriptive per page |
| 10 | Language attribute | `<html lang="en">` |
| 11 | Error identification | Form errors are text, not color-only |
| 12 | Error suggestions | Tell users how to fix the error |
| 13 | Link purpose clear | No "click here" or "read more" without context |
| 14 | Button text | No icon-only buttons without `aria-label` |
| 15 | Table headers | `<th scope="col|row">` on data tables |
| 16 | No seizure content | No flashing > 3 times/sec |
| 17 | Status messages | `role="status"` or `aria-live` for dynamic updates |
| 18 | Reflow at 400% zoom | Single column, no horizontal scroll |
| 19 | Text spacing adjustable | No overflow when line-height/letter-spacing increased |
| 20 | Timeout warning | Warn before session expires, allow extension |

## Keyboard Navigation Test Patterns

### Tab order verification
```typescript
test('modal tab order is correct', async ({ page }) => {
  await page.click('[data-testid="open-modal"]')

  // First focus should be the modal's close button or heading
  await expect(page.locator('[aria-label="Close dialog"]')).toBeFocused()

  // Tab through: close → input → submit
  await page.keyboard.press('Tab')
  await expect(page.locator('#email-input')).toBeFocused()

  await page.keyboard.press('Tab')
  await expect(page.locator('[type="submit"]')).toBeFocused()

  // Wrap back to close button (focus trap)
  await page.keyboard.press('Tab')
  await expect(page.locator('[aria-label="Close dialog"]')).toBeFocused()
})
```

### Focus trap in modals
```typescript
// Escape should close
await page.keyboard.press('Escape')
await expect(page.locator('[role="dialog"]')).not.toBeVisible()

// Focus returns to trigger element after close
await expect(page.locator('[data-testid="open-modal"]')).toBeFocused()
```

### Skip navigation link
```typescript
test('skip link goes to main content', async ({ page }) => {
  await page.goto('/')
  await page.keyboard.press('Tab')   // first tab = skip link

  const skipLink = page.locator('a:has-text("Skip to")')
  await expect(skipLink).toBeFocused()

  await page.keyboard.press('Enter')
  await expect(page.locator('main, #main-content')).toBeFocused()
})
```

### Arrow key navigation (listbox/menu)
```typescript
test('dropdown menu responds to arrow keys', async ({ page }) => {
  await page.click('[aria-haspopup="listbox"]')
  await page.keyboard.press('ArrowDown')  // first option focused
  await page.keyboard.press('ArrowDown')  // second option
  await page.keyboard.press('Enter')      // select

  // Verify selection
  await expect(page.locator('[aria-selected="true"]')).toContainText('Option 2')
})
```

## ARIA Patterns

### Live regions (dynamic announcements)
```html
<!-- For important real-time updates (errors, confirmations) -->
<div role="alert">Your payment failed. Please try again.</div>

<!-- For polite updates (search results count) -->
<div aria-live="polite" aria-atomic="true">
  Showing 42 results for "laptop"
</div>

<!-- Screen reader only text (visually hidden) -->
<style>
  .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;
  }
</style>
```

### Dialog / Modal
```html
<div role="dialog"
     aria-modal="true"
     aria-labelledby="dialog-title"
     aria-describedby="dialog-desc">
  <h2 id="dialog-title">Confirm Delete</h2>
  <p id="dialog-desc">This action cannot be undone.</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>
```

### Tabs
```html
<div role="tablist" aria-label="Account settings">
  <button role="tab" aria-selected="true"  aria-controls="panel-profile" id="tab-profile">Profile</button>
  <button role="tab" aria-selected="false" aria-controls="panel-billing" id="tab-billing" tabindex="-1">Billing</button>
</div>
<div role="tabpanel" id="panel-profile" aria-labelledby="tab-profile">...</div>
<div role="tabpanel" id="panel-billing" aria-labelledby="tab-billing" hidden>...</div>
```

### Combobox / Autocomplete
```html
<label for="search">Search users</label>
<input type="text"
       id="search"
       role="combobox"
       aria-autocomplete="list"
       aria-expanded="true"
       aria-controls="search-listbox"
       aria-activedescendant="opt-2" />
<ul id="search-listbox" role="listbox">
  <li role="option" id="opt-1">Alice</li>
  <li role="option" id="opt-2" aria-selected="true">Bob</li>
</ul>
```

## Color Contrast Requirements

| Text Size | Minimum Ratio | Enhanced (AAA) |
|-----------|--------------|----------------|
| Normal text (< 18pt / < 14pt bold) | 4.5:1 | 7:1 |
| Large text (≥ 18pt or ≥ 14pt bold) | 3:1 | 4.5:1 |
| UI components / icons | 3:1 | — |
| Decorative / disabled | No requirement | — |

Test tools: [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/), Figma A11y Plugin, Chrome DevTools CSS Overview.

## VoiceOver Quick Reference (macOS)

| Action | Shortcut |
|--------|----------|
| Start / Stop VoiceOver | Cmd + F5 |
| Read next item | VO + Right Arrow |
| Read page from top | VO + A |
| Navigate headings | VO + Cmd + H |
| Navigate links | VO + Cmd + L |
| Navigate form controls | VO + Cmd + J |
| Open Web Rotor | VO + U |

VO = Control + Option

## Common Violations and Fixes

```html
<!-- VIOLATION: Missing alt -->
<img src="logo.png" />
<!-- FIX -->
<img src="logo.png" alt="Acme Corp logo" />
<!-- Decorative: -->
<img src="divider.png" alt="" role="presentation" />

<!-- VIOLATION: Icon button with no label -->
<button><svg>...</svg></button>
<!-- FIX -->
<button aria-label="Close dialog"><svg aria-hidden="true">...</svg></button>

<!-- VIOLATION: Placeholder as label -->
<input placeholder="Email address" />
<!-- FIX -->
<label for="email">Email address</label>
<input id="email" type="email" placeholder="you@example.com" />

<!-- VIOLATION: Color-only error -->
<input style="border: 2px solid red" />
<!-- FIX -->
<input aria-invalid="true" aria-describedby="email-error" />
<span id="email-error" role="alert">Email is required</span>
```

## CI Integration (axe-core in GitHub Actions)

```yaml
# .github/workflows/a11y.yml
name: Accessibility Tests
on: [pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run test:a11y
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: a11y-report
          path: playwright-report/
```

Related Skills

python-testing

422

from vibeeval/vibecosystem

Python testing strategies using pytest, TDD methodology, fixtures, mocking, parametrization, and coverage requirements.

property-based-testing

422

from vibeeval/vibecosystem

Property-based testing (PBT) patterns with fast-check (JS/TS), Hypothesis (Python), and gopter (Go). Generate random inputs, define invariants, shrink failures to minimal cases. Adapted from Trail of Bits. Use when testing pure functions, parsers, serializers, state machines, or any code where example-based tests miss edge cases.

performance-testing

422

from vibeeval/vibecosystem

Load testing with k6/Artillery, response time thresholds, memory leak detection, N+1 query detection, and CI integration.

load-testing-patterns

422

from vibeeval/vibecosystem

k6 script templates, load profiles, response time thresholds, SLO validation, and performance testing strategies.

golang-testing

422

from vibeeval/vibecosystem

Go testing patterns including table-driven tests, subtests, benchmarks, fuzzing, and test coverage. Follows TDD methodology with idiomatic Go practices.

contract-testing-patterns

422

from vibeeval/vibecosystem

Pact consumer-driven contracts, provider verification, schema evolution

workflow-router

422

from vibeeval/vibecosystem

Goal-based workflow orchestration - routes tasks to specialist agents based on user goals

wiring

422

from vibeeval/vibecosystem

Wiring Verification

websocket-patterns

422

from vibeeval/vibecosystem

Connection management, room patterns, reconnection strategies, message buffering, and binary protocol design.

visual-verdict

422

from vibeeval/vibecosystem

Screenshot comparison QA for frontend development. Takes a screenshot of the current implementation, scores it across multiple visual dimensions, and returns a structured PASS/REVISE/FAIL verdict with concrete fixes. Use when implementing UI from a design reference or verifying visual correctness.

verification-loop

422

from vibeeval/vibecosystem

Comprehensive verification system covering build, types, lint, tests, security, and diff review before a PR.

vector-db-patterns

422

from vibeeval/vibecosystem

Embedding strategies, ANN algorithms, hybrid search, RAG chunking strategies, and reranking for semantic search and retrieval.