npm package: @gtcx/accessibility
Description: Inclusive design — tech literacy adaptation, WCAG contrast, a11y React hooks
Latest version: 0.1.0

# @gtcx/accessibility

Inclusive design system for GTCX Protocol — tech literacy adaptation, WCAG compliance, and universal access.

## Features

- **Tech Literacy Levels** — Beginner, intermediate, advanced UX adaptation
- **WCAG 2.1 AA Compliance** — Full accessibility standards
- **Offline Accessibility** — Screen readers, voice control without connectivity
- **Multi-Modal Input** — Voice, touch, gesture, keyboard
- **Cognitive Accessibility** — Clear language, consistent design, error prevention

## Installation

```bash
pnpm add @gtcx/accessibility
```

## Usage

```typescript
import { AccessibilityService, TechLiteracyLevel, detectTechLiteracy } from '@gtcx/accessibility';

// Initialize accessibility service
const a11y = new AccessibilityService({
  wcagLevel: 'AA',
  techLiteracy: 'beginner',
  offlineEnabled: true,
});

// Detect user's tech literacy from interaction patterns
const literacy = await detectTechLiteracy(userInteractions);
// Returns: 'beginner' | 'intermediate' | 'advanced'

// Adapt UI complexity based on literacy level
const uiConfig = a11y.getUIConfig(literacy);
/*
  beginner: Large buttons, simple nav, audio guidance, step-by-step
  intermediate: Standard UI, contextual help, keyboard shortcuts
  advanced: Power user features, API access, customization
*/

// Voice guidance for low-literacy users
await a11y.speak('Please tap the green button to continue', {
  language: 'sw', // Swahili
  speed: 'slow',
});
```

## Tech Literacy Adaptation

The system adapts based on user capability:

### Beginner Level

- **Visual**: Large buttons (min 48px), clear icons, simple navigation
- **Guidance**: Step-by-step wizards, progress indicators, audio instructions
- **Input**: Touch-friendly, voice input, minimal typing
- **Feedback**: Immediate visual + audio confirmation

### Intermediate Level

- **Visual**: Standard controls, contextual help tooltips
- **Guidance**: Guided setup with skip options
- **Input**: Keyboard shortcuts available, form auto-complete
- **Feedback**: Visual confirmation, optional audio

### Advanced Level

- **Visual**: Compact UI, power-user features visible
- **Guidance**: Help available on demand
- **Input**: Full keyboard control, CLI available, API access
- **Feedback**: Minimal, non-intrusive

## WCAG Compliance

```typescript
// Check element accessibility
const issues = a11y.audit(element);
/*
  [
    { rule: 'color-contrast', severity: 'error', element: '#btn1' },
    { rule: 'alt-text', severity: 'warning', element: 'img.logo' }
  ]
*/

// Get compliant color palette
const colors = a11y.getAccessibleColors({
  primary: '#1a5f2a',
  background: '#ffffff',
  minContrast: 4.5, // WCAG AA
});

// Generate accessible form
const form = a11y.createAccessibleForm({
  fields: ['name', 'email', 'phone'],
  labelPosition: 'above', // Better for screen readers
  errorAnnouncement: 'polite',
});
```

## Offline Capabilities

All accessibility features work offline:

- **Screen Reader Support** — Pre-cached ARIA labels
- **Voice Guidance** — Offline TTS with local voices
- **Keyboard Navigation** — No network required
- **High Contrast** — Local CSS, no CDN

## Multi-Modal Input

```typescript
// Enable voice control
a11y.enableVoiceControl({
  language: 'en-GH', // Ghanaian English
  commands: {
    next: () => nextStep(),
    back: () => prevStep(),
    help: () => showHelp(),
    submit: () => submitForm(),
  },
});

// Enable gesture control
a11y.enableGestures({
  swipeLeft: () => prevStep(),
  swipeRight: () => nextStep(),
  doubleTap: () => select(),
  longPress: () => showOptions(),
});
```

## Architecture

```
packages/accessibility/
├── src/
│   ├── index.ts              # Main exports
│   ├── service.ts            # AccessibilityService
│   ├── tech-literacy.ts      # Literacy detection & adaptation
│   ├── wcag/                 # WCAG compliance utilities
│   │   ├── audit.ts
│   │   ├── colors.ts
│   │   └── forms.ts
│   ├── input/                # Multi-modal input
│   │   ├── voice.ts
│   │   ├── gesture.ts
│   │   └── keyboard.ts
│   ├── output/               # Accessible output
│   │   ├── screen-reader.ts
│   │   ├── tts.ts
│   │   └── haptic.ts
│   └── types.ts
└── configs/
    └── literacy-levels.yaml  # UI configs per level
```

## Related Packages

- `@gtcx/i18n` — Multi-language support with cultural adaptation
- `@gtcx/offline-sync` — Offline-first data synchronization
- `@gtcx/ui` — Base component library