@sucoza/accessibility-devtools-plugin

Accessibility DevTools Plugin

A comprehensive accessibility auditing plugin for TanStack DevTools that provides real-time WCAG compliance testing, color contrast analysis, keyboard navigation visualization, ARIA validation, and more.

Features

🔍 Comprehensive Accessibility Auditing

• Real-time accessibility scanning with axe-core integration
• WCAG 2.1 compliance testing (A, AA, AAA levels)
• Automated detection of common accessibility issues
• Performance-optimized continuous scanning

🎨 Color Contrast Analysis

• WCAG AA/AAA color contrast compliance checking
• Visual color swatch display
• Contrast ratio calculations
• Accessible color suggestions

⌨️ Keyboard Navigation Testing

• Tab order visualization
• Focus flow debugging
• Keyboard trap detection
• Skip link validation

🛡️ ARIA Validation

• Comprehensive ARIA attribute validation
• Role verification and redundancy detection
• Missing accessible name detection
• Reference integrity checking

🗺️ Landmark Structure Analysis

• Page structure visualization
• Landmark hierarchy mapping
• Missing landmark detection
• Visual overlay for page regions

🎯 Focus Management Debugging

• Real-time focus tracking
• Focus indicator visibility testing
• Focus history tracking
• Poor contrast detection for focus states

Installation

npm install @sucoza/accessibility-devtools-plugin

Usage

Basic Setup

import React from 'react';
import { AccessibilityDevToolsPanel } from '@sucoza/accessibility-devtools-plugin';

function App() {
  return (
    <div>
      {/* Your app content */}
      
      {/* Accessibility DevTools Panel */}
      <AccessibilityDevToolsPanel />
    </div>
  );
}

With Event Client Integration

import React, { useEffect } from 'react';
import { 
  AccessibilityDevToolsPanel,
  createAccessibilityDevToolsEventClient 
} from '@sucoza/accessibility-devtools-plugin';

function App() {
  useEffect(() => {
    // Initialize the accessibility event client
    const client = createAccessibilityDevToolsEventClient();
    
    // Optional: Listen for accessibility events
    const unsubscribe = client.subscribe((event, type) => {
      if (type === 'accessibility:issue-found') {
        console.log('New accessibility issue:', event);
      }
    });
    
    return unsubscribe;
  }, []);

  return (
    <div>
      <AccessibilityDevToolsPanel />
    </div>
  );
}

Using the Hook

import React from 'react';
import { useAccessibilityAudit } from '@sucoza/accessibility-devtools-plugin';

function MyComponent() {
  const {
    currentAudit,
    scanState,
    startScan,
    getIssueStats
  } = useAccessibilityAudit();
  
  const stats = getIssueStats();
  
  return (
    <div>
      <button onClick={() => startScan()}>
        Start Accessibility Scan
      </button>
      
      {currentAudit && (
        <div>
          <p>Issues found: {stats.total}</p>
          <p>Critical: {stats.critical}</p>
          <p>Serious: {stats.serious}</p>
        </div>
      )}
    </div>
  );
}

Configuration

Scan Options

import { useAccessibilityAudit } from '@sucoza/accessibility-devtools-plugin';

function MyComponent() {
  const { updateScanOptions } = useAccessibilityAudit();
  
  // Configure scanning behavior
  updateScanOptions({
    continuous: true,
    debounceMs: 1000,
    includeColorContrast: true,
    includeKeyboardNav: true,
    includeARIA: true,
    includeFocus: true,
    config: {
      wcagLevel: 'AA',
      includeExperimental: false,
    }
  });
}

Settings

import { useAccessibilityAudit } from '@sucoza/accessibility-devtools-plugin';

function MyComponent() {
  const { updateSettings } = useAccessibilityAudit();
  
  // Configure plugin settings
  updateSettings({
    autoScan: true,
    scanDelay: 1000,
    maxHistoryEntries: 50,
    enableOverlay: true,
    enableSounds: false,
    enableNotifications: true,
    wcagLevel: 'AA',
    includeExperimental: false,
  });
}

Components

AccessibilityDevToolsPanel

The main panel component that provides the complete accessibility auditing interface.

Individual Components

You can also use individual components for specific functionality:

• IssueList - Display accessibility violations
• ColorContrastAnalyzer - Color contrast analysis tool
• KeyboardNavVisualizer - Keyboard navigation testing
• ARIAValidator - ARIA attribute validation
• LandmarkMapper - Page structure analysis
• FocusDebugger - Focus management debugging

API Reference

Types

interface AccessibilityIssue {
  id: string;
  rule: string;
  impact: SeverityLevel;
  description: string;
  help: string;
  helpUrl: string;
  tags: string[];
  nodes: AccessibilityNode[];
  type: ViolationType;
  timestamp: number;
}

interface AccessibilityAuditResult {
  url: string;
  timestamp: number;
  violations: AccessibilityIssue[];
  incomplete: AccessibilityIssue[];
  passes: AccessibilityIssue[];
  inapplicable: AccessibilityIssue[];
  testEngine: {
    name: string;
    version: string;
  };
  // ... more properties
}

Event Client

interface AccessibilityDevToolsEvents {
  'accessibility:state': AccessibilityDevToolsState;
  'accessibility:action': AccessibilityDevToolsAction;
  'accessibility:audit-started': { timestamp: number; elementSelector?: string };
  'accessibility:audit-complete': { audit: AccessibilityAuditResult; metrics: ScanPerformanceMetrics };
  'accessibility:issue-found': { issue: AccessibilityIssue; isNew: boolean };
  'accessibility:overlay-toggle': { enabled: boolean; state: OverlayState };
  'accessibility:element-highlight': { selector: string | null };
}

Examples

Check out the example/ directory for a complete demonstration of the plugin with various accessibility issues to test against.

To run the example:

cd example
npm install
npm run dev

Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

License

MIT

Part of the @sucoza TanStack DevTools ecosystem.

Powered By

• axe-core - Accessibility engine
• TanStack DevTools - Development tools framework
• Zustand - State management
• colorjs.io - Color manipulation and contrast calculations