accessibility-testing-expert
Expert guide for automated and manual Web Accessibility (a11y) testing — axe-core, Pa11y, Playwright a11y, screen reader testing, and WCAG 2.2 Level AA/AAA compliance / Panduan ahli pengujian aksesibilitas web.
Roedy Rustam · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add roedyrustam/vibes-plug --skill accessibility-testing-expertAbout this skill
name: accessibility-testing-expert description: "Expert guide for automated and manual Web Accessibility (a11y) testing — axe-core, Pa11y, Playwright a11y, screen reader testing, and WCAG 2.2 Level AA/AAA compliance / Panduan ahli pengujian aksesibilitas web." author: "Roedy Rustam"
version: "4.2.0"
Accessibility Testing Expert (2026 Edition)
English
Orchestration & Integration
global-a11y-i18n-expert: Core WCAG rules, ARIA patterns, and internationalization standards.e2e-testing-expert: Integrating automated accessibility assertions into Playwright/Vitest CI suites.design-system-architect, senior-frontend: Accessible component primitives (Radix UI, Base UI, ARIA patterns).browser-automation-expert: Visual QA audits for focus rings, contrast ratios, and layout flow using Vision LLM agents.anti-slop: Enforces strict accessibility rules (preventing stripped focus outlines, div-soup buttons, and color contrast violations).
Description
Production guide for automated, semi-automated, and manual web accessibility (a11y) testing. Covers WCAG 2.2 Level AA/AAA compliance validation using @axe-core/playwright, Pa11y, Google Lighthouse CI, screen reader verification (NVDA, VoiceOver), keyboard navigation audits, focus management, and color contrast compliance.
Trigger Conditions
- Running automated accessibility test suites in CI/CD pipelines.
- Auditing web apps for WCAG 2.1 / 2.2 Level AA compliance and legal accessibility requirements (ADA, EAA).
- Debugging keyboard traps, missing ARIA labels, or broken screen reader navigation.
- Writing test cases for focus trapping in modals and custom dialogs.
Core Testing Workflows
1. Automated A11y Testing with Playwright & Axe-Core
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test.describe('Accessibility Automated Audits', () => {
test('homepage should have zero critical or serious a11y violations', async ({ page }) => {
await page.goto('/');
const accessibilityScanResults = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
.disableRules(['color-contrast']) // If tested separately
.analyze();
expect(accessibilityScanResults.violations).toEqual([]);
});
test('modal dialog should trap focus and pass a11y audit', async ({ page }) => {
await page.goto('/dashboard');
await page.click('button#open-modal');
// Verify modal is open and focused
const modal = page.locator('[role="dialog"]');
await expect(modal).toBeVisible();
const modalAudit = await new AxeBuilder({ page })
.include('[role="dialog"]')
.analyze();
expect(modalAudit.violations).toEqual([]);
// Verify keyboard escape closes modal
await page.keyboard.press('Escape');
await expect(modal).toBeHidden();
});
});
2. Automated Pa11y CI Configuration (.pa11yci.json)
{
"defaults": {
"standard": "WCAG2AA",
"timeout": 15000,
"runners": ["axe", "htmlcs"],
"ignore": [
"WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Abs"
]
},
"urls": [
"http://localhost:3000/",
"http://localhost:3000/login",
"http://localhost:3000/pricing",
"http://localhost:3000/docs"
]
}
3. Keyboard & Screen Reader Verification Checklist
- Tab Navigation: All interactive elements (
<button>,<a>,<input>) can receive focus in logical reading order. - Focus Indicators: Visible, high-contrast focus rings (
outline: 2px solid var(--focus-color)withoutline-offset). - No Keyboard Traps: Focus can enter and leave components using only
Tab,Shift+Tab, andEsc. - Landmarks: Proper semantic tags (
<header>,<nav>,<main>,<footer>,<aside>). - ARIA Attributes:
aria-expanded,aria-controls,aria-haspopup, andaria-liveupdated dynamically.
4. Material Design 3 (M3) Accessibility & State Layer Assertions (https://m3.material.io/foundations/accessible-design/overview)
M3 enforces rigorous interaction states via standardized State Layer Opacities and an expanded 48×48dp Target Size:
1. M3 State Layer Opacity Matrix:
- Hover: 8% (
0.08) overlay ofon-surfaceorprimary. - Focus: 10% (
0.10) overlay with high-contrast ring. - Pressed: 10% (
0.10) overlay. - Dragged: 16% (
0.16) overlay. - Disabled: Container opacity
38%(0.38), content opacity38%(0.38).
2. 48×48dp Minimum Touch Target Assertion (Playwright):
import { test, expect } from '@playwright/test';
test('interactive controls satisfy M3 48x48dp touch target standard', async ({ page }) => {
await page.goto('/');
const buttons = page.locator('button, a[role="button"], input[type="checkbox"]');
const count = await buttons.count();
for (let i = 0; i < count; i++) {
const btn = buttons.nth(i);
const box = await btn.boundingBox();
if (box && await btn.isVisible()) {
// M3 requires min 48x48dp bounding box for touch targets
expect(box.width).toBeGreaterThanOrEqual(48);
expect(box.height).toBeGreaterThanOrEqual(48);
}
}
});
5. Sovereign Anti-Slop A11y Verification Gate
Zero-tolerance accessibility criteria for all generated interfaces:
- No Stripped Focus Outlines: Zero tolerance for
outline: noneorfocus:outline-nonewithout an explicit, high-contrast replacement ring (focus-visible:ring-2 focus-visible:ring-offset-2). - Semantic Elements Only: Ban on non-semantic clickable divs/spans (
<div onClick=...>). Every click target must be an authentic<button>,<a>, or providerole="button"+tabIndex={0}+ keyboard event handlers (onKeyDownfor Enter & Space). - Touch Target Minimums: All interactive controls must satisfy WCAG 2.2 SC 2.5.8 (minimum 24×24px, recomme