Agent skill
accessibility-testing
Audit and test web accessibility with automated scanning, manual screen reader testing, and WCAG 2.2 remediation. Use when auditing accessibility, fixing WCAG violations, testing with screen readers, or implementing accessible components.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/accessibility-testing-jlaws-dotfiles
SKILL.md
Accessibility Testing
Automated Testing Setup
axe-core: Use AxePuppeteer with .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']) for automated audits. Exclude non-audited regions with .exclude().
jest-axe: Use toHaveNoViolations() matcher in component tests.
CLI Tools
npx @axe-core/cli https://example.com
npx pa11y https://example.com --standard WCAG2AA --threshold 0
lighthouse https://example.com --only-categories=accessibility
CI/CD: Run npx pa11y against localhost in CI. Gate PRs on zero WCAG2AA violations.
Manual Screen Reader Testing
Testing Priority
Minimum: NVDA + Firefox (Win), VoiceOver + Safari (Mac), VoiceOver + Safari (iOS)
Full: + JAWS + Chrome (Win), TalkBack + Chrome (Android)
VoiceOver (macOS) Commands
VO = Ctrl + Option
Toggle: Cmd + F5
Next/Prev element: VO + Right/Left Arrow
Enter/Exit group: VO + Shift + Down/Up
Read all: VO + A
Activate: VO + Space
Rotor: VO + U (navigate by headings, links, forms, landmarks)
Next heading: VO + Cmd + H
Next form control: VO + Cmd + J
Next link: VO + Cmd + L
NVDA (Windows) Commands
NVDA modifier = Insert
Say all: NVDA + Down Arrow
Elements list: NVDA + F7
Quick keys (browse mode):
H/Shift+H Heading next/prev D/Shift+D Landmark next/prev
F Next form field B Next button
K Next link T Next table
Table nav: Ctrl + Alt + Arrows
Mode switch: NVDA + Space (browse <-> focus)
JAWS Quick Keys
H Next heading T Next table F Next form field
B Next button ; Next landmark G Next graphic
Insert + F7 Link list Insert + F6 Heading list
Test Script (All Screen Readers)
- Page load - Title announced? Main landmark found? Skip link works?
- Landmark nav - All main areas reachable? Properly labeled?
- Heading nav - Logical structure? All sections discoverable?
- Form testing - Labels read? Required fields announced? Errors announced? Focus moved to error?
- Interactive elements - Each announces role + state? Activates with Enter/Space?
- Dynamic content - Updates announced? Modal traps focus? Focus returns on close?
Common Screen Reader Fixes
<!-- Button without visible text -->
<button aria-label="Close dialog"><svg aria-hidden="true">...</svg></button>
<!-- Dynamic content not announced -->
<div role="status" aria-live="polite">New results loaded</div>
<!-- Form error not read -->
<input type="email" aria-invalid="true" aria-describedby="email-error">
<span id="email-error" role="alert">Invalid email</span>
WCAG 2.2 Audit Checklist
Critical Violations (Blockers)
- All functional images have alt text; decorative images
alt="" - All interactive elements keyboard accessible (no traps)
- All form inputs have associated labels
- Color contrast: 4.5:1 text, 3:1 large text/UI components
- No auto-playing media without controls
Serious Violations
- Skip to main content link present
- Page titles unique and descriptive
- Heading hierarchy logical (no skipped levels)
- ARIA landmarks defined (main, nav, etc.)
- Focus indicator visible on all elements (3:1 contrast)
-
<html lang="en">attribute set
Forms & Interaction
- Error messages identify field and describe problem
- Required fields indicated (not color-only)
-
aria-invalid="true"+aria-describedbyon error fields - Live regions:
role="status"(polite) /role="alert"(assertive) - Modal dialogs:
role="dialog",aria-modal="true", focus trap, Esc to close
Responsive & Motion
- Content reflows at 320px (no horizontal scroll)
- Text resizes to 200% without loss
-
@media (prefers-reduced-motion: reduce)disables animations -
@media (prefers-contrast: high)increases contrast
Remediation Patterns
Keyboard nav widgets: Custom interactive widgets need: tabindex="0", role, aria-expanded, and keydown handler for Enter/Space (activate), Escape (close), Arrow keys (navigate).
Focus management for modals: Save document.activeElement before opening. Trap Tab/Shift+Tab within modal's focusable elements. Restore focus on close.
Tab interface: Use role="tablist"/role="tab"/role="tabpanel" with aria-selected, aria-controls, aria-labelledby. Arrow keys navigate tabs, Home/End jump to first/last.
Color contrast: Use @media (prefers-contrast: high) and visible :focus outlines (3px solid, 2px offset).
Cross-References
- frontend:design-system-patterns -- accessible headless components, ARIA defaults
- frontend:form-patterns -- accessible forms, labels, error messages, aria-describedby
- frontend:web-animation-patterns -- reduced-motion preferences, prefers-reduced-motion
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?