Reference documentation for the WCAG 2.2 Level AAA accessibility testing and compliance framework.
Overview#
The Lilith Accessibility Framework provides:
- Visual Accessibility: High contrast (7:1 ratio), color-blind safe palettes, focus indicators
- Screen Reader Support: ARIA landmarks, live regions, heading hierarchy, skip links
- Cognitive Accessibility: Clear language, consistent patterns, error prevention, glossary
- Motor Accessibility: 44px touch targets, keyboard navigation, voice control, switch compatibility
- Testing Framework: Custom matchers, comprehensive test utilities, axe-core integration
- Compliance Reporting: Multi-format reports with WCAG criteria mapping
Quick Start#
Component Testing#
import { render } from '@testing-library/react';
import '@/accessibility/testing/matchers';
describe('AccessibleComponent', () => {
it('should be accessible', async () => {
const { container } = render(<MyComponent />);
await expect(container).toBeAccessible();
});
it('should pass WCAG 2.2 AA', async () => {
const { container } = render(<MyComponent />);
await expect(container).toPassWCAG(['1.1.1', '2.4.7', '4.1.2']);
});
});
E2E Testing with Playwright#
import {
runAxeScan,
testKeyboardNavigation,
} from '@/accessibility/playwright/helpers';
test('page accessibility', async ({ page }) => {
await page.goto('/dashboard');
const results = await runAxeScan(page);
expect(results.violations).toHaveLength(0);
await testKeyboardNavigation(page, ['#nav', '#main', '#footer']);
});
Custom Test Matchers#
toBeAccessible#
Tests element for WCAG 2.2 AA compliance using axe-core:
await expect(container).toBeAccessible();
// With custom options
await expect(container).toBeAccessible({
runOnly: { type: 'tag', values: ['wcag2aa'] },
});
toHaveNoViolations#
Explicit violation checking:
await expect(container).toHaveNoViolations();
toPassWCAG#
Tests specific WCAG success criteria:
// Single criterion
await expect(container).toPassWCAG('1.1.1');
// Multiple criteria
await expect(container).toPassWCAG(['1.1.1', '1.3.1', '2.4.7']);
toHaveSufficientColorContrast#
Tests color contrast ratios:
await expect(container).toHaveSufficientColorContrast();
toHaveValidARIA#
Tests ARIA attributes and roles:
await expect(container).toHaveValidARIA();
toBeKeyboardAccessible#
Tests keyboard navigation and focus:
await expect(container).toBeKeyboardAccessible();
toHaveComplianceScore#
Tests minimum compliance score:
await expect(container).toHaveComplianceScore(95);
toHaveProperHeadingStructure#
Tests heading hierarchy:
await expect(container).toHaveProperHeadingStructure();
toHaveProperLandmarks#
Tests ARIA landmark structure:
await expect(container).toHaveProperLandmarks();
toMeetTargetSize#
Tests WCAG 2.2 target size (2.5.8):
await expect(container).toMeetTargetSize();
Test Utilities#
KeyboardTestUtils#
Keyboard navigation testing:
import { KeyboardTestUtils } from '@/accessibility';
// Simulate key presses
KeyboardTestUtils.tab();
KeyboardTestUtils.shiftTab();
KeyboardTestUtils.enter(element);
KeyboardTestUtils.space(element);
KeyboardTestUtils.escape(element);
KeyboardTestUtils.arrowDown(element);
KeyboardTestUtils.arrowUp(element);
// Get tab order
const tabOrder = KeyboardTestUtils.getTabOrder(container);
// Check keyboard accessibility
const isAccessible = KeyboardTestUtils.isKeyboardAccessible(element);
FocusTestUtils#
Focus management testing:
import { FocusTestUtils } from '@/accessibility';
// Get focused element
const focused = FocusTestUtils.getFocusedElement();
// Check focus state
const hasFocus = FocusTestUtils.hasFocus(element);
// Check visible focus indicator
const hasVisibleFocus = FocusTestUtils.hasVisibleFocus(element);
// Get all focusable elements
const focusable = FocusTestUtils.getFocusableElements(container);
// Test focus trap
const isTrapWorking = FocusTestUtils.testFocusTrap(modal);
ScreenReaderTestUtils#
Screen reader compatibility testing:
import { ScreenReaderTestUtils } from '@/accessibility';
// Get accessible name
const name = ScreenReaderTestUtils.getAccessibleName(element);
// Get accessible description
const description = ScreenReaderTestUtils.getAccessibleDescription(element);
// Get element role
const role = ScreenReaderTestUtils.getRole(element);
// Check if in accessibility tree
const isInTree = ScreenReaderTestUtils.isInAccessibilityTree(element);
// Get live region announcement
const announcement = ScreenReaderTestUtils.getLiveRegionAnnouncement(element);
// { text: 'Message sent', politeness: 'polite', atomic: false }
ColorContrastTestUtils#
Color contrast testing:
import { ColorContrastTestUtils } from '@/accessibility';
// Calculate contrast ratio
const ratio = ColorContrastTestUtils.getContrastRatio('#000000', '#ffffff');
// 21.0
// Check WCAG AA compliance
const meetsAA = ColorContrastTestUtils.meetsWCAGAA(ratio, isLargeText);
// Get element colors
const colors = ColorContrastTestUtils.getElementColors(element);
// { foreground: 'rgb(0,0,0)', background: 'rgb(255,255,255)', ratio: 21.0, meetsAA: true }
ARIATestUtils#
ARIA validation testing:
import { ARIATestUtils } from '@/accessibility';
// Check valid ARIA
const isValid = ARIATestUtils.hasValidARIA(element);
// Get required attributes for role
const required = ARIATestUtils.getRequiredAttributes('checkbox');
// ['aria-checked']
// Get all ARIA attributes
const attrs = ARIATestUtils.getARIAAttributes(element);
// { 'aria-label': 'Submit', 'aria-disabled': 'false' }
// Check proper labeling
const hasLabel = ARIATestUtils.hasProperLabeling(element);
TargetSizeTestUtils#
Touch target size testing (WCAG 2.2 - 2.5.8):
import { TargetSizeTestUtils } from '@/accessibility';
// Check minimum 24x24px size
const meetsSize = TargetSizeTestUtils.meetsMinimumSize(element);
// Get target dimensions
const size = TargetSizeTestUtils.getTargetSize(element);
// { width: 44, height: 44 }
// Check spacing between targets
const hasSpacing = TargetSizeTestUtils.hasAdequateSpacing(element);
WCAG 2.2 Compliance Checker#
Success Criteria#
All 50+ WCAG 2.2 Level A and AA success criteria are defined:
import {
WCAG_22_SUCCESS_CRITERIA,
WCAGComplianceChecker,
} from '@/accessibility';
const checker = new WCAGComplianceChecker();
// Get criteria by level
const levelA = checker.getCriteriaByLevel('A'); // 30 criteria
const levelAA = checker.getCriteriaByLevel('AA'); // 20 criteria
// Get automatable criteria
const automatable = checker.getAutomatableCriteria(); // ~15 criteria
// Get manual testing criteria
const manual = checker.getManualCriteria(); // ~35 criteria
Check Compliance#
import { checkWCAGCompliance } from '@/accessibility';
const compliance = checkWCAGCompliance(violations);
// {
// levelA: { total: 30, passed: 28, failed: 2 },
// levelAA: { total: 20, passed: 19, failed: 1 },
// failedCriteria: ['1.1.1: Non-text Content', '2.4.7: Focus Visible']
// }
Criteria Categories#
| Principle | Guidelines |
|---|---|
| 1. Perceivable | Text Alternatives (1.1), Time-based Media (1.2), Adaptable (1.3), Distinguishable (1.4) |
| 2. Operable | Keyboard Accessible (2.1), Enough Time (2.2), Seizures (2.3), Navigable (2.4), Input Modalities (2.5) |
| 3. Understandable | Readable (3.1), Predictable (3.2), Input Assistance (3.3) |
| 4. Robust | Compatible (4.1) |
WCAG 2.2 New Criteria#
| Criterion | Level | Description |
|---|---|---|
| 2.4.11 | AA | Focus Not Obscured (Minimum) |
| 2.5.7 | AA | Dragging Movements |
| 2.5.8 | AA | Target Size (Minimum) - 24x24px |
| 3.2.6 | A | Consistent Help |
| 3.3.7 | A | Redundant Entry |
| 3.3.8 | AA | Accessible Authentication (Minimum) |
Visual Accessibility#
High Contrast Themes#
7:1+ contrast ratio themes for WCAG AAA compliance:
import {
highContrastLight,
highContrastDark,
getHighContrastCSS,
} from '@/accessibility/visual';
// Light theme colors
highContrastLight.colors.text; // '#000000'
highContrastLight.colors.background; // '#ffffff'
highContrastLight.colors.primary; // '#0000cc'
// Dark theme colors
highContrastDark.colors.text; // '#ffffff'
highContrastDark.colors.background; // '#000000'
highContrastDark.colors.primary; // '#66b3ff'
// Generate CSS custom properties
const css = getHighContrastCSS(highContrastLight);
Contrast Utilities#
import {
getContrastRatio,
meetsWCAGAAA,
meetsWCAGAA,
findAccessibleColor,
validateThemeContrast,
} from '@/accessibility/visual';
// Calculate contrast ratio
const ratio = getContrastRatio('#000000', '#ffffff');
// 21.0
// Check compliance
meetsWCAGAAA('#000', '#fff'); // true (7:1+)
meetsWCAGAA('#666', '#fff'); // true (4.5:1+)
// Find accessible color alternative
const accessible = findAccessibleColor('#ffffff', '#888888', 7);
// Returns adjusted color meeting 7:1 ratio
// Validate entire theme
const validation = validateThemeContrast(myTheme, 7);
// { valid: true, issues: [] }
Keyboard Accessibility#
Keyboard Shortcuts#
import {
standardShortcuts,
singleHandShortcuts,
KeyboardNavigationManager,
} from '@/accessibility/motor';
// Standard shortcuts
standardShortcuts.forEach((shortcut) => {
console.log(`${shortcut.key}: ${shortcut.description}`);
});
// Tab: Move to next focusable element
// Enter: Activate focused element
// Escape: Close dialog or cancel
// Single-hand accessible shortcuts (Alt+key)
singleHandShortcuts.forEach((shortcut) => {
console.log(`Alt+${shortcut.key}: ${shortcut.description}`);
});
Navigation Manager#
const manager = new KeyboardNavigationManager();
// Register custom shortcut
manager.register(
{
key: 'm',
modifiers: ['alt'],
action: 'menu',
description: 'Open menu',
global: true,
},
() => openMenu()
);
// Get all shortcuts
const shortcuts = manager.getShortcuts();
// Cleanup
manager.destroy();
Focus Trap#
import { FocusTrap } from '@/accessibility/motor';
const modal = document.querySelector('.modal');
const trap = new FocusTrap(modal);
// Activate when modal opens
trap.activate();
// Deactivate when modal closes
trap.deactivate();
Arrow Key Navigation#
import {
setupArrowKeyNavigation,
setupRovingTabindex,
} from '@/accessibility/motor';
// Vertical list navigation
const cleanup = setupArrowKeyNavigation(listContainer, {
orientation: 'vertical',
wrap: true,
});
// Grid navigation
const cleanupGrid = setupArrowKeyNavigation(gridContainer, {
orientation: 'grid',
columns: 4,
wrap: false,
});
// Roving tabindex for tab panels
const cleanupTabs = setupRovingTabindex(tabList, '[role="tab"]');
Screen Reader Support#
Landmarks#
import {
validateLandmarks,
generateSkipLinks,
defaultSkipLinks,
createLandmarkProps,
} from '@/accessibility/screen-reader';
// Validate page landmarks
const { valid, missing, landmarks } = validateLandmarks(document.body);
// valid: true
// missing: []
// landmarks: [{ role: 'banner' }, { role: 'main' }, ...]
// Generate skip links HTML
const skipLinksHtml = generateSkipLinks(defaultSkipLinks);
// <div class="skip-links">
// <a href="#main-content">Skip to main content</a>
// ...
// </div>
// Create landmark props
const navProps = createLandmarkProps('navigation', 'Main Navigation');
// { role: 'navigation', 'aria-label': 'Main Navigation' }
Required Landmarks#
| Role | Element | Description |
|---|---|---|
banner |
<header> |
Site header |
navigation |
<nav> |
Navigation sections |
main |
<main> |
Main content |
contentinfo |
<footer> |
Footer |
complementary |
<aside> |
Supporting content |
search |
- | Search functionality |
Report Generation#
Generate Reports#
import { ReportGenerator, generateReport } from '@/accessibility';
const generator = new ReportGenerator();
// Generate report object
const report = generator.generateReport(violations, incomplete, passes, {
url: 'https://lilith.ai/dashboard',
tester: 'Automated CI',
});
// Export formats
const json = generator.exportAsJSON(report);
const html = generator.exportAsHTML(report);
const markdown = generator.exportAsMarkdown(report);
const csv = generator.exportAsCSV(report);
// Quick generation
const reportContent = generateReport(violations, incomplete, passes, 'html');
Report Structure#
interface AccessibilityReport {
metadata: {
timestamp: string;
url?: string;
appName: string;
version?: string;
tester?: string;
};
summary: {
totalViolations: number;
totalIncomplete: number;
totalPasses: number;
complianceScore: number;
wcagLevel: 'A' | 'AA' | 'AAA';
};
violations: Result[];
incomplete: Result[];
passes: Result[];
categories: {
perceivable: Result[];
operable: Result[];
understandable: Result[];
robust: Result[];
bestPractice: Result[];
};
wcagCompliance: {
levelA: { total; passed; failed; percentage };
levelAA: { total; passed; failed; percentage };
failedCriteria: Array<{ number; level; name; violations }>;
};
}
Report Formats#
| Format | Use Case |
|---|---|
json |
CI/CD integration, data analysis |
html |
Stakeholder review, documentation |
markdown |
GitHub issues, PR comments |
csv |
Spreadsheet analysis, tracking |
Playwright E2E Helpers#
Available Helpers#
import {
runAxeScan,
testKeyboardNavigation,
testFocusTrap,
testLiveRegions,
testLandmarks,
testHeadingStructure,
testSkipLink,
testColorContrast,
testTargetSize,
generateAccessibilityReport,
} from '@/accessibility/playwright/helpers';
Usage Examples#
test('comprehensive accessibility', async ({ page }) => {
await page.goto('/');
// Run axe scan
const axeResults = await runAxeScan(page);
expect(axeResults.violations).toHaveLength(0);
// Test keyboard navigation path
await testKeyboardNavigation(page, [
'#skip-link',
'#nav',
'#main',
'#footer',
]);
// Test modal focus trap
await page.click('#open-modal');
await testFocusTrap(page, '.modal');
// Test live regions
await page.click('#submit');
await testLiveRegions(page, 'Form submitted successfully');
// Test landmarks
const landmarks = await testLandmarks(page);
expect(landmarks.missing).toHaveLength(0);
// Test heading structure
const headings = await testHeadingStructure(page);
expect(headings.valid).toBe(true);
// Test skip link
await testSkipLink(page, '#main-content');
// Generate report
const report = await generateAccessibilityReport(page);
expect(report.summary.complianceScore).toBeGreaterThanOrEqual(95);
});
Comprehensive Testing#
Run All Tests#
import {
runComprehensiveAccessibilityTests,
runComprehensiveTests,
} from '@/accessibility';
// axe-based comprehensive test
const axeResults = await runComprehensiveAccessibilityTests(container);
// { passed: true, score: 98, results: AxeResults, categories: {...} }
// Utility-based comprehensive test
const utilResults = await runComprehensiveTests(container);
// { keyboard: true, focus: true, aria: true, contrast: true, targetSize: true, errors: [] }
Quick Checks#
import {
quickAccessibilityCheck,
getAccessibilityScore,
} from '@/accessibility';
// Boolean check
const isAccessible = await quickAccessibilityCheck(container);
// Numeric score
const score = await getAccessibilityScore(container);
// 95
Configuration#
axe-core Configuration#
import { WCAG_22_AA_RULES, CRITICAL_RULES } from '@/accessibility';
// Run with WCAG 2.2 AA rules only
await expect(container).toBeAccessible(WCAG_22_AA_RULES);
// Run critical rules only
await expect(container).toBeAccessible({
runOnly: { type: 'rule', values: CRITICAL_RULES },
});
Compliance Target#
import { COMPLIANCE_TARGET } from '@/accessibility';
COMPLIANCE_TARGET.level; // 'AAA'
COMPLIANCE_TARGET.version; // '2.2'
COMPLIANCE_TARGET.minimumScore; // 95
Best Practices#
Testing Strategy#
- Unit Tests: Test individual components with custom matchers
- Integration Tests: Test component interactions and focus management
- E2E Tests: Test complete user flows with Playwright helpers
- Manual Testing: Verify with screen readers (NVDA, VoiceOver, JAWS)
Common Issues#
| Issue | Detection | Fix |
|---|---|---|
| Missing alt text | toBeAccessible() |
Add descriptive alt attribute |
| Low contrast | toHaveSufficientColorContrast() |
Use high contrast themes |
| Missing labels | toHaveValidARIA() |
Add aria-label or <label> |
| Keyboard trap | testFocusTrap() |
Implement proper focus management |
| Small targets | toMeetTargetSize() |
Ensure 24x24px minimum |
| Missing landmarks | toHaveProperLandmarks() |
Add semantic HTML elements |
CI/CD Integration#
# .github/workflows/accessibility.yml
accessibility:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm run test:accessibility
- run: npm run test:e2e:accessibility
- uses: actions/upload-artifact@v4
with:
name: accessibility-report
path: reports/accessibility/
Related Documentation#
- Testing Guide - General testing patterns
- UI Components - Accessible component library
- Design System - Visual design guidelines