@gtcx/accessibility 0.1.0

package/README.md

@@ -0,0 +1,163 @@
+# @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

package/dist/index.d.mts

@@ -0,0 +1,183 @@
+import * as react from 'react';
+import { RefObject } from 'react';
+
+/**
+ * Tech Literacy Detection and Adaptation
+ *
+ * Automatically detects user's technical proficiency and adapts UI accordingly
+ */
+type TechLiteracyLevel = 'beginner' | 'intermediate' | 'advanced';
+interface InteractionPattern {
+    /** Time to complete action in ms */
+    actionTime: number;
+    /** Number of errors/corrections */
+    errorCount: number;
+    /** Used keyboard shortcuts */
+    usedShortcuts: boolean;
+    /** Scrolled to find features */
+    searchedFeatures: boolean;
+    /** Requested help */
+    requestedHelp: boolean;
+    /** Used voice input */
+    usedVoice: boolean;
+    /** Interaction timestamp */
+    timestamp: number;
+}
+interface LiteracyScore {
+    level: TechLiteracyLevel;
+    confidence: number;
+    signals: string[];
+}
+/**
+ * Detect tech literacy level from interaction patterns
+ */
+declare function detectTechLiteracy(interactions: InteractionPattern[]): Promise<LiteracyScore>;
+/**
+ * Tech literacy detector with continuous learning
+ */
+declare class TechLiteracyDetector {
+    private interactions;
+    private currentLevel;
+    private onLevelChange?;
+    constructor(options?: {
+        initialLevel?: TechLiteracyLevel;
+        onLevelChange?: (level: TechLiteracyLevel) => void;
+    });
+    /**
+     * Record an interaction for analysis
+     */
+    recordInteraction(pattern: Omit<InteractionPattern, 'timestamp'>): void;
+    /**
+     * Evaluate current literacy level
+     */
+    evaluate(): Promise<LiteracyScore>;
+    /**
+     * Get current assessed level
+     */
+    getLevel(): TechLiteracyLevel;
+    /**
+     * Manually set level (user preference)
+     */
+    setLevel(level: TechLiteracyLevel): void;
+}
+declare const LITERACY_UI_CONFIGS: {
+    readonly beginner: {
+        readonly buttonSize: "large";
+        readonly fontSize: "large";
+        readonly navigation: "simple";
+        readonly icons: "labeled";
+        readonly animations: "minimal";
+        readonly guidance: "proactive";
+        readonly inputMode: "touch";
+        readonly errorHandling: "guided";
+        readonly confirmations: "explicit";
+        readonly shortcuts: "hidden";
+    };
+    readonly intermediate: {
+        readonly buttonSize: "medium";
+        readonly fontSize: "medium";
+        readonly navigation: "standard";
+        readonly icons: "tooltips";
+        readonly animations: "standard";
+        readonly guidance: "contextual";
+        readonly inputMode: "mixed";
+        readonly errorHandling: "inline";
+        readonly confirmations: "smart";
+        readonly shortcuts: "discoverable";
+    };
+    readonly advanced: {
+        readonly buttonSize: "compact";
+        readonly fontSize: "small";
+        readonly navigation: "full";
+        readonly icons: "minimal";
+        readonly animations: "full";
+        readonly guidance: "on-demand";
+        readonly inputMode: "keyboard";
+        readonly errorHandling: "technical";
+        readonly confirmations: "minimal";
+        readonly shortcuts: "prominent";
+    };
+};
+
+/**
+ * WCAG color contrast utilities.
+ *
+ * Implements the WCAG 2.1 relative luminance and contrast ratio algorithm
+ * for checking foreground/background color accessibility.
+ */
+/** Calculate relative luminance per WCAG 2.1. */
+declare function relativeLuminance(hex: string): number;
+/** Calculate the contrast ratio between two hex colors. */
+declare function contrastRatio(fg: string, bg: string): number;
+/**
+ * Check if a foreground/background pair meets WCAG contrast requirements.
+ *
+ * @param fg  Foreground hex color (e.g. `'#333333'`)
+ * @param bg  Background hex color (e.g. `'#ffffff'`)
+ * @param level `'AA'` (4.5:1 normal, 3:1 large) or `'AAA'` (7:1 normal, 4.5:1 large)
+ * @param large Whether the text is "large" (>= 18pt or >= 14pt bold)
+ */
+declare function meetsWCAG(fg: string, bg: string, level?: 'AA' | 'AAA', large?: boolean): boolean;
+
+/**
+ * React hook for detecting `prefers-reduced-motion` media query.
+ *
+ * Returns `true` when the user has enabled reduced motion in their
+ * OS accessibility settings. Components should disable non-essential
+ * animations when this is `true`.
+ *
+ * @example
+ * ```tsx
+ * const reduced = useReducedMotion();
+ * return <div style={{ transition: reduced ? 'none' : 'all 0.3s' }} />;
+ * ```
+ */
+declare function useReducedMotion(): boolean;
+
+/**
+ * React hook for trapping focus within a container element.
+ *
+ * Used for modals, dialogs, and drawers to ensure keyboard users
+ * cannot Tab outside the container while it is active.
+ *
+ * @example
+ * ```tsx
+ * function Modal({ open, children }) {
+ *   const ref = useFocusTrap<HTMLDivElement>(open);
+ *   return open ? <div ref={ref} role="dialog">{children}</div> : null;
+ * }
+ * ```
+ */
+
+declare function useFocusTrap<T extends HTMLElement>(active: boolean): RefObject<T | null>;
+
+/**
+ * React hook for screen reader announcements via `aria-live` regions.
+ *
+ * Creates an invisible live region and provides an `announce()` function
+ * that dynamically updates its content, causing screen readers to
+ * read the message aloud.
+ *
+ * @example
+ * ```tsx
+ * const { announce, liveRegionProps } = useAnnounce();
+ * // Place the live region once in your layout:
+ * <div {...liveRegionProps} />
+ * // Then announce messages:
+ * announce('3 items selected');
+ * ```
+ */
+interface LiveRegionProps {
+    role: 'status';
+    'aria-live': 'polite' | 'assertive';
+    'aria-atomic': boolean;
+    style: Record<string, string | number>;
+}
+declare function useAnnounce(politeness?: 'polite' | 'assertive'): {
+    announce: (message: string) => void;
+    liveRegionProps: LiveRegionProps & {
+        ref: react.MutableRefObject<HTMLElement | null>;
+    };
+};
+
+export { LITERACY_UI_CONFIGS, type LiveRegionProps, TechLiteracyDetector, type TechLiteracyLevel, contrastRatio, detectTechLiteracy, meetsWCAG, relativeLuminance, useAnnounce, useFocusTrap, useReducedMotion };

package/dist/index.d.ts

@@ -0,0 +1,183 @@
+import * as react from 'react';
+import { RefObject } from 'react';
+
+/**
+ * Tech Literacy Detection and Adaptation
+ *
+ * Automatically detects user's technical proficiency and adapts UI accordingly
+ */
+type TechLiteracyLevel = 'beginner' | 'intermediate' | 'advanced';
+interface InteractionPattern {
+    /** Time to complete action in ms */
+    actionTime: number;
+    /** Number of errors/corrections */
+    errorCount: number;
+    /** Used keyboard shortcuts */
+    usedShortcuts: boolean;
+    /** Scrolled to find features */
+    searchedFeatures: boolean;
+    /** Requested help */
+    requestedHelp: boolean;
+    /** Used voice input */
+    usedVoice: boolean;
+    /** Interaction timestamp */
+    timestamp: number;
+}
+interface LiteracyScore {
+    level: TechLiteracyLevel;
+    confidence: number;
+    signals: string[];
+}
+/**
+ * Detect tech literacy level from interaction patterns
+ */
+declare function detectTechLiteracy(interactions: InteractionPattern[]): Promise<LiteracyScore>;
+/**
+ * Tech literacy detector with continuous learning
+ */
+declare class TechLiteracyDetector {
+    private interactions;
+    private currentLevel;
+    private onLevelChange?;
+    constructor(options?: {
+        initialLevel?: TechLiteracyLevel;
+        onLevelChange?: (level: TechLiteracyLevel) => void;
+    });
+    /**
+     * Record an interaction for analysis
+     */
+    recordInteraction(pattern: Omit<InteractionPattern, 'timestamp'>): void;
+    /**
+     * Evaluate current literacy level
+     */
+    evaluate(): Promise<LiteracyScore>;
+    /**
+     * Get current assessed level
+     */
+    getLevel(): TechLiteracyLevel;
+    /**
+     * Manually set level (user preference)
+     */
+    setLevel(level: TechLiteracyLevel): void;
+}
+declare const LITERACY_UI_CONFIGS: {
+    readonly beginner: {
+        readonly buttonSize: "large";
+        readonly fontSize: "large";
+        readonly navigation: "simple";
+        readonly icons: "labeled";
+        readonly animations: "minimal";
+        readonly guidance: "proactive";
+        readonly inputMode: "touch";
+        readonly errorHandling: "guided";
+        readonly confirmations: "explicit";
+        readonly shortcuts: "hidden";
+    };
+    readonly intermediate: {
+        readonly buttonSize: "medium";
+        readonly fontSize: "medium";
+        readonly navigation: "standard";
+        readonly icons: "tooltips";
+        readonly animations: "standard";
+        readonly guidance: "contextual";
+        readonly inputMode: "mixed";
+        readonly errorHandling: "inline";
+        readonly confirmations: "smart";
+        readonly shortcuts: "discoverable";
+    };
+    readonly advanced: {
+        readonly buttonSize: "compact";
+        readonly fontSize: "small";
+        readonly navigation: "full";
+        readonly icons: "minimal";
+        readonly animations: "full";
+        readonly guidance: "on-demand";
+        readonly inputMode: "keyboard";
+        readonly errorHandling: "technical";
+        readonly confirmations: "minimal";
+        readonly shortcuts: "prominent";
+    };
+};
+
+/**
+ * WCAG color contrast utilities.
+ *
+ * Implements the WCAG 2.1 relative luminance and contrast ratio algorithm
+ * for checking foreground/background color accessibility.
+ */
+/** Calculate relative luminance per WCAG 2.1. */
+declare function relativeLuminance(hex: string): number;
+/** Calculate the contrast ratio between two hex colors. */
+declare function contrastRatio(fg: string, bg: string): number;
+/**
+ * Check if a foreground/background pair meets WCAG contrast requirements.
+ *
+ * @param fg  Foreground hex color (e.g. `'#333333'`)
+ * @param bg  Background hex color (e.g. `'#ffffff'`)
+ * @param level `'AA'` (4.5:1 normal, 3:1 large) or `'AAA'` (7:1 normal, 4.5:1 large)
+ * @param large Whether the text is "large" (>= 18pt or >= 14pt bold)
+ */
+declare function meetsWCAG(fg: string, bg: string, level?: 'AA' | 'AAA', large?: boolean): boolean;
+
+/**
+ * React hook for detecting `prefers-reduced-motion` media query.
+ *
+ * Returns `true` when the user has enabled reduced motion in their
+ * OS accessibility settings. Components should disable non-essential
+ * animations when this is `true`.
+ *
+ * @example
+ * ```tsx
+ * const reduced = useReducedMotion();
+ * return <div style={{ transition: reduced ? 'none' : 'all 0.3s' }} />;
+ * ```
+ */
+declare function useReducedMotion(): boolean;
+
+/**
+ * React hook for trapping focus within a container element.
+ *
+ * Used for modals, dialogs, and drawers to ensure keyboard users
+ * cannot Tab outside the container while it is active.
+ *
+ * @example
+ * ```tsx
+ * function Modal({ open, children }) {
+ *   const ref = useFocusTrap<HTMLDivElement>(open);
+ *   return open ? <div ref={ref} role="dialog">{children}</div> : null;
+ * }
+ * ```
+ */
+
+declare function useFocusTrap<T extends HTMLElement>(active: boolean): RefObject<T | null>;
+
+/**
+ * React hook for screen reader announcements via `aria-live` regions.
+ *
+ * Creates an invisible live region and provides an `announce()` function
+ * that dynamically updates its content, causing screen readers to
+ * read the message aloud.
+ *
+ * @example
+ * ```tsx
+ * const { announce, liveRegionProps } = useAnnounce();
+ * // Place the live region once in your layout:
+ * <div {...liveRegionProps} />
+ * // Then announce messages:
+ * announce('3 items selected');
+ * ```
+ */
+interface LiveRegionProps {
+    role: 'status';
+    'aria-live': 'polite' | 'assertive';
+    'aria-atomic': boolean;
+    style: Record<string, string | number>;
+}
+declare function useAnnounce(politeness?: 'polite' | 'assertive'): {
+    announce: (message: string) => void;
+    liveRegionProps: LiveRegionProps & {
+        ref: react.MutableRefObject<HTMLElement | null>;
+    };
+};
+
+export { LITERACY_UI_CONFIGS, type LiveRegionProps, TechLiteracyDetector, type TechLiteracyLevel, contrastRatio, detectTechLiteracy, meetsWCAG, relativeLuminance, useAnnounce, useFocusTrap, useReducedMotion };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,iBAAiB,EAClB,MAAM,iBAAiB,CAAC"}