@ordojs/accessibility

Comprehensive accessibility system for OrdoJS with ARIA generation, automated testing, and screen reader support.

Features

• ARIA Generation: Automatic ARIA attribute generation and validation
• Automated Testing: Accessibility testing with axe-core, Puppeteer, and JSDOM
• Focus Management: Focus trap, skip links, and keyboard navigation
• Screen Reader Support: Announcements and live regions
• Color Contrast: WCAG-compliant color contrast checking
• Semantic HTML: Automatic semantic HTML generation
• CLI Tools: Command-line interface for accessibility management
• WCAG Compliance: Support for WCAG A, AA, and AAA levels

Installation

pnpm add @ordojs/accessibility

Quick Start

Basic Usage

import { AccessibilityManager } from '@ordojs/accessibility';

// Create accessibility manager
const a11y = new AccessibilityManager({
  enableARIA: true,
  enableTesting: true,
  enableFocusManagement: true,
  enableScreenReader: true,
  wcagLevel: 'AA',
});

// Initialize the system
await a11y.initialize();

// Run accessibility audit
const audit = await a11y.runAudit('https://example.com', {
  level: 'AA',
  rules: ['color-contrast', 'keyboard-navigation'],
  timeout: 30000,
});

console.log(`Accessibility Score: ${audit.score}%`);
console.log(`Compliant: ${audit.compliant}`);

ARIA Generation

import { ARIAManager } from '@ordojs/accessibility/aria';

const ariaManager = new ARIAManager(config);

// Generate ARIA attributes
const ariaAttributes = ariaManager.generateARIA(
  {
    tag: 'button',
    content: 'Submit',
    attributes: { type: 'submit' },
  },
  {
    role: 'button',
    label: 'Submit form',
    state: { pressed: false },
  }
);

// Validate ARIA attributes
const validation = ariaManager.validateARIA(ariaAttributes);
if (!validation.isValid) {
  console.log('ARIA validation errors:', validation.errors);
}

Focus Management

import { FocusManager } from '@ordojs/accessibility/focus';

const focusManager = new FocusManager(config);

// Register focusable elements
focusManager.registerFocusableElement('#submit-button', {
  tabIndex: 0,
  focusOrder: 1,
  ariaLabel: 'Submit form',
});

// Create focus trap for modal
focusManager.createFocusTrap('modal-trap', ['#modal-close', '#modal-content', '#modal-submit'], {
  initialFocus: '#modal-content',
  returnFocus: true,
});

// Handle keyboard navigation
document.addEventListener('keydown', event => {
  const result = focusManager.handleKeyboardNavigation(event, '#current-element');
  if (result.handled) {
    console.log('Navigation action:', result.action);
  }
});

Screen Reader Support

import { ScreenReaderManager } from '@ordojs/accessibility/screen-reader';

const srManager = new ScreenReaderManager(config);

// Create announcement
const announcementId = srManager.announce('Form submitted successfully', {
  priority: 'polite',
  type: 'status',
});

// Create live region
const region = srManager.createLiveRegion('status-region', '#status', {
  type: 'status',
  priority: 'polite',
  atomic: true,
});

// Update live region content
srManager.updateLiveRegion('status-region', 'Processing...', {
  busy: true,
});

Automated Testing

import { TestingManager } from '@ordojs/accessibility/testing';

const testingManager = new TestingManager({
  enabled: true,
  framework: 'axe-core',
  rules: ['color-contrast', 'keyboard-navigation'],
  timeout: 30000,
});

// Run tests
const results = await testingManager.runTests('https://example.com', {
  rules: ['color-contrast'],
  timeout: 15000,
});

// Generate report
const report = testingManager.generateReport(results, {
  format: 'html',
  includeViolations: true,
});

CLI Usage

Installation

pnpm add -g @ordojs/accessibility

Commands

Audit Command

# Run accessibility audit
ordojs-a11y audit https://example.com

# Run audit with specific options
ordojs-a11y audit https://example.com \
  --level AA \
  --rules color-contrast,keyboard-navigation \
  --timeout 30000 \
  --output html \
  --file audit-report.html

Test Command

# Run specific test
ordojs-a11y test https://example.com --name color-contrast

# Run tests with framework
ordojs-a11y test https://example.com \
  --framework puppeteer \
  --timeout 30000 \
  --retries 3

Generate ARIA Command

# Generate ARIA for HTML file
ordojs-a11y generate-aria ./src/components.html \
  --output ./aria-output \
  --format html \
  --validate

Focus Management Command

# Analyze focus order
ordojs-a11y focus --analyze ./src/components.html

# Generate focus management code
ordojs-a11y focus --generate ./src/components.html

# Test keyboard navigation
ordojs-a11y focus --test ./src/components.html

Screen Reader Command

# Create announcement
ordojs-a11y screen-reader --announce "Form submitted successfully"

# Create live region
ordojs-a11y screen-reader --live-region status-region

# Update live region
ordojs-a11y screen-reader --update status-region "Processing..."

Report Command

# Generate report from audit results
ordojs-a11y report \
  --input audit-results.json \
  --output report.html \
  --format html \
  --summary \
  --detailed

Stats Command

# Show overall statistics
ordojs-a11y stats

# Show focus management statistics
ordojs-a11y stats --focus

# Show screen reader statistics
ordojs-a11y stats --screen-reader

Configuration

Accessibility Configuration

interface AccessibilityConfig {
  // Enable features
  enableARIA: boolean;
  enableTesting: boolean;
  enableFocusManagement: boolean;
  enableScreenReader: boolean;
  enableKeyboardNavigation: boolean;
  enableColorContrast: boolean;
  enableSemanticHTML: boolean;
  enableLiveRegions: boolean;
  enableSkipLinks: boolean;
  enableFocusIndicators: boolean;

  // WCAG compliance level
  wcagLevel: 'A' | 'AA' | 'AAA';

  // Custom ARIA rules
  customARIA: Record<string, any>;

  // Sub-configurations
  testing: TestingConfig;
  focus: FocusConfig;
  screenReader: ScreenReaderConfig;
}

Testing Configuration

interface TestingConfig {
  enabled: boolean;
  framework: 'axe-core' | 'puppeteer' | 'jsdom';
  rules: string[];
  ignoreRules: string[];
  timeout: number;
  retries: number;
  generateReports: boolean;
  reportFormat: 'json' | 'html' | 'csv';
  reportDir: string;
}

Focus Configuration

interface FocusConfig {
  enabled: boolean;
  focusTrap: boolean;
  focusIndicators: boolean;
  skipLinks: boolean;
  focusOrder: 'tab' | 'logical' | 'custom';
  focusRestoration: boolean;
  focusDelegation: boolean;
}

Screen Reader Configuration

interface ScreenReaderConfig {
  enabled: boolean;
  announcements: boolean;
  liveRegions: boolean;
  ariaLabels: boolean;
  ariaDescriptions: boolean;
  ariaLandmarks: boolean;
  ariaRoles: boolean;
  ariaStates: boolean;
  ariaProperties: boolean;
}

API Reference

AccessibilityManager

Main accessibility manager class.

Methods

• initialize(): Initialize the accessibility system
• runAudit(url, options): Run accessibility audit
• generateARIA(element, context): Generate ARIA attributes
• checkColorContrast(foreground, background): Check color contrast
• generateSemanticHTML(content, options): Generate semantic HTML
• getStats(): Get accessibility statistics
• updateConfig(newConfig): Update configuration

ARIAManager

ARIA attribute generation and validation.

Methods

• initialize(): Initialize ARIA manager
• generateARIA(element, context): Generate ARIA attributes
• validateARIA(attributes): Validate ARIA attributes
• getRoleInfo(role): Get role information
• getAttributeInfo(attribute): Get attribute information
• getAvailableRoles(): Get all available roles
• getAvailableAttributes(): Get all available attributes
• getRolesByType(type): Get roles by type
• getStats(): Get ARIA statistics

FocusManager

Focus management and keyboard navigation.

Methods

• initialize(): Initialize focus manager
• registerFocusableElement(element, info): Register focusable element
• createFocusTrap(trapId, elements, options): Create focus trap
• removeFocusTrap(trapId, options): Remove focus trap
• setFocus(element): Set focus to element
• moveToNextElement(currentElement): Move to next element
• moveToPreviousElement(currentElement): Move to previous element
• addSkipLink(target, label, position): Add skip link
• removeSkipLink(target): Remove skip link
• handleKeyboardNavigation(event, currentElement): Handle keyboard navigation
• getFocusableElements(): Get focusable elements
• getFocusTrapElements(trapId): Get focus trap elements
• getSkipLinks(): Get skip links
• getFocusedElement(): Get currently focused element
• getStats(): Get focus statistics

ScreenReaderManager

Screen reader announcements and live regions.

Methods

• initialize(): Initialize screen reader manager
• announce(message, options): Create announcement
• createLiveRegion(regionId, element, options): Create live region
• updateLiveRegion(regionId, content, options): Update live region
• removeLiveRegion(regionId): Remove live region
• getLiveRegion(regionId): Get live region
• getAllLiveRegions(): Get all live regions
• getAnnouncement(announcementId): Get announcement
• getAllAnnouncements(): Get all announcements
• clearAnnouncements(): Clear announcements
• getStats(): Get screen reader statistics

TestingManager

Automated accessibility testing.

Methods

• initialize(): Initialize testing manager
• runTests(url, options): Run accessibility tests
• runTest(testName, url, options): Run specific test
• generateReport(results, options): Generate test report
• getTestResult(testId): Get test result
• getAllTestResults(): Get all test results
• clearTestResults(): Clear test results
• getStats(): Get testing statistics

Supported WCAG Criteria

Level A

• 1.1.1 Non-text Content
• 1.2.1 Audio-only and Video-only (Prerecorded)
• 1.2.2 Captions (Prerecorded)
• 1.2.3 Audio Description or Media Alternative (Prerecorded)
• 1.3.1 Info and Relationships
• 1.3.2 Meaningful Sequence
• 1.3.3 Sensory Characteristics
• 1.4.1 Use of Color
• 2.1.1 Keyboard
• 2.1.2 No Keyboard Trap
• 2.2.1 Timing Adjustable
• 2.2.2 Pause, Stop, Hide
• 2.3.1 Three Flashes or Below Threshold
• 2.4.1 Bypass Blocks
• 2.4.2 Page Titled
• 2.4.3 Focus Order
• 2.4.4 Link Purpose (In Context)
• 3.1.1 Language of Page
• 3.2.1 On Focus
• 3.2.2 On Input
• 3.3.1 Error Identification
• 3.3.2 Labels or Instructions
• 4.1.1 Parsing
• 4.1.2 Name, Role, Value

Level AA

• 1.2.4 Captions (Live)
• 1.2.5 Audio Description (Prerecorded)
• 1.4.3 Contrast (Minimum)
• 1.4.4 Resize Text
• 1.4.5 Images of Text
• 2.4.5 Multiple Ways
• 2.4.6 Headings and Labels
• 2.4.7 Focus Visible
• 3.1.2 Language of Parts
• 3.2.3 Consistent Navigation
• 3.2.4 Consistent Identification
• 3.3.3 Error Suggestion
• 3.3.4 Error Prevention (Legal, Financial, Data)
• 4.1.3 Status Messages

Level AAA

• 1.2.6 Sign Language (Prerecorded)
• 1.2.7 Extended Audio Description (Prerecorded)
• 1.2.8 Media Alternative (Prerecorded)
• 1.2.9 Audio-only (Live)
• 1.4.6 Contrast (Enhanced)
• 1.4.7 Low or No Background Audio
• 1.4.8 Visual Presentation
• 1.4.9 Images of Text (No Exception)
• 2.1.3 Keyboard (No Exception)
• 2.2.1 Timing Adjustable
• 2.2.2 Pause, Stop, Hide
• 2.3.2 Three Flashes
• 2.4.8 Location
• 2.4.9 Link Purpose (Link Only)
• 2.4.10 Section Headings
• 2.5.5 Target Size
• 2.5.6 Input Mechanisms
• 3.1.3 Unusual Words
• 3.1.4 Abbreviations
• 3.1.5 Reading Level
• 3.1.6 Pronunciation
• 3.2.1 On Focus
• 3.2.2 On Input
• 3.2.3 Consistent Navigation
• 3.2.4 Consistent Identification
• 3.3.1 Error Identification
• 3.3.2 Labels or Instructions
• 3.3.3 Error Suggestion
• 3.3.4 Error Prevention (Legal, Financial, Data)
• 3.3.5 Help
• 3.3.6 Error Prevention (All)
• 4.1.3 Status Messages

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Node.js Support

• Node.js 18+

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run tests: pnpm test
6. Submit a pull request

License

MIT License - see LICENSE file for details.