accessibility-testing

Files (24)

• AGENTS.md
• README.md
• SKILL.md
• metadata.json
• _sections.md · rules/
• _template.md · rules/
• accessibility-testing-combine-automated-testing-axe-core-in-playwright-with.md · rules/
• accessibility-testing-configure-a.md · rules/
• accessibility-testing-enable-addon-a11y-for-all-stories-by-default.md · rules/
• accessibility-testing-fail-the-build-on-critical-violations-missing-alt-text.md · rules/
• accessibility-testing-generate-reports-as-ci-artifacts-for-audit-trails-and.md · rules/
• accessibility-testing-include-people-with-disabilities-in-user-testing-when.md · rules/
• accessibility-testing-run-automated-a11y-tests-on-every-pr.md · rules/
• accessibility-testing-test-components-in-isolation-and-in-composed-layouts.md · rules/
• accessibility-testing-test-pages-in-multiple-states-empty-loaded-error-modal.md · rules/
• accessibility-testing-test-with-real-assistive-technology-at-least-once-per.md · rules/
• accessibility-testing-treat-a11y-violations-like-bugs-not-warnings.md · rules/
• accessibility-testing-use-actions-for-authenticated-pages-or-spas-that-need.md · rules/
• accessibility-testing-use-axe-core-react-during-development-to-catch-issues.md · rules/
• accessibility-testing-use-ignore-sparingly-and-document-why-each-rule-is-ignored.md · rules/
• accessibility-testing-use-include-exclude-to-scope-checks-to-specific.md · rules/
• accessibility-testing-use-the-storybook-test-runner-with-axe-playwright-for-ci.md · rules/
• accessibility-testing-use-withtags-wcag2a-wcag2aa-wcag21aa-for.md · rules/
• accessibility-testing-warn-on-moderate-violations-contrast-heading-order-to.md · rules/

SKILL.md (first lines)

# Accessibility Testing

## Overview
Accessibility testing ensures your application is usable by people with disabilities, including those who rely on screen readers, keyboard navigation, voice control, and other assistive technologies. Automated tools can catch 30-50% of WCAG violations; the rest requires manual testing and judgment.

## WCAG Compliance Levels

| Level | Meaning | Examples | Target |
|-------|---------|----------|--------|
| **A** | Minimum | Alt text on images, keyboard accessible, no seizure-inducing content | Bare minimum for all sites |
| **AA** | Standard | Color contrast 4.5:1, resize to 200%, visible focus indicators | **Most common target** (legal requirement in many jurisdictions) |
| **AAA** | Enhanced | Contrast 7:1, sign language for media, no timing limits | Aspirational — rarely required in full |

### WCAG 2.2 Key Updates (over 2.1)
- **2.4.11 Focus Not Obscured (Minimum)** — Focus indicator not fully hidden by other content.
- **2.4.13 Focus Appearance** — Visible focus indicator meets minimum size/contrast.
- **2.5.7 Dragging Movements** — Drag operations have non-dragging alternatives.
- **2.5.8 Target Size (Minimum)** — Touch targets at least 24x24 CSS pixels.
- **3.3.7 Redundant Entry** — Don't ask users to re-enter previously provided info.
- **3.3.8 Accessible Authentication (Minimum)** — No cognitive function test for login.

## Common Violations (Caught by Automation)

| Violation | WCAG Criterion | Impact |
|-----------|---------------|--------|
| Missing alt text on images | 1.1.1 Non-text Content | Critical — screen readers skip images |
| Insufficient color contrast | 1.4.3 Contrast (Minimum) | Serious — affects low vision users |
| Missing form labels | 1.3.1 Info and Relationships | Critical — form fields unidentifiable |
| Missing document language | 3.1.1 Language of Page | Moderate — screen readers use wrong pronunciation |
| Empty links / buttons | 4.1.2 Name, Role, Value | Critical — controls have no accessible name |
| Missing skip navigation link | 2.4.1 Bypass Blocks | Moderate — keyboard users cannot skip repeated content |
| Duplicate element IDs | 4.1.1 Parsing | Moderate — ARIA references break |
| Missing heading structure | 1.3.1 Info and Relationships | Serious — navigation by headings fails |

---

## Cross-Platform Tools

| Tool | Type | Best For |
|------|------|----------|
| **axe-core** | Library / Engine | Programmatic integration into any test framework |
| **@axe-core/playwright** | Playwright integration | E2E accessibility testing in Playwright |
| **@axe-core/react** | React dev tool | Component-level checks during development |
| **Pa11y** | CLI + Dashboard | CI pipelines, page-level audits, monitoring |
| **Lighthouse** | CLI / Chrome DevTools | Performance + accessibility audits combined |
| **Storybook addon-a11y** | Storybook addon | Component-level checks in design system |
| **WAVE** | Browser extension | Manual audits, visual overlay of issues |

---

## axe-core

### Overview
axe-core is the industry-standard accessibility testing engine by Deque. It powers most automated a11y tools and can be integrated into any testing framework.

### Playwright + axe-core Integration

```javascript
// tests/a11y/homepage.spec.js
import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test.describe("Homepage accessibility", () => {
    test("should have no WCAG 2.1 AA violations", async ({ page }) => {
        await page.goto("/");

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

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

    test("should have no violations in the navigation", async ({ page }) => {
        await page.goto("/");

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

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

    test("should have no violations after modal opens", async ({ page }) => {
        await page.goto("/");
        await page.click("button#open-modal");
        await page.waitForSelector("[role='dialog']");

        const results = await new AxeBuilder({ page })
            .include("[role='dialog']")
            .analyze();

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

### axe-core with Detailed Reporting

```javascript
// tests/a11y/helpers.js
import AxeBuilder from "@axe-core/playwright";

export async function checkA11y(page, context, options = {}) {
    const builder = new AxeBuilder({ page })
        .withTags(options.tags || ["wcag2a", "wcag2aa", "wcag21aa"]);

    if (options.include) builder.include(options.include);
    if (options.exclude) builder.exclude(options.exclude);
    if (options.disableRules) builder.disableRules(options.disableRules);

    const results = await builder.analyze();

    if (results.violations.length > 0) {
        const report = results.violations.map((v) => ({
            id: v.id,
            impact: v.impact,
            description: v.description,
            helpUrl: v.helpUrl,

From onfire7777/universal-ai-skills-library, MIT.

More from onfire7777/universal-ai-skills-library