feat: accessibility audit + KeyboardNav composable utility

Audit findings: 91/123 components have ariaLabel (74%), 90 have role
attrs, but only 1/123 has keyboard handlers. Critical gap documented.

KeyboardNav.res provides composable keyboard patterns:
- onActivate (Enter/Space), onEscape, onVerticalNav, onHorizontalNav
- onListNav (full dropdown/combobox pattern)
- srOnly helper, livePolite/liveAssertive region wrappers
- focusable/focusableHidden tabIndex helpers

766 modules compile clean.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

docs/ACCESSIBILITY-AUDIT-2026-03-29.md

@@ -0,0 +1,103 @@
+<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
+<!-- Accessibility Audit — 2026-03-29 -->
+
+# PanLL Accessibility Audit
+
+**Date:** 2026-03-29
+**Auditor:** Claude (automated scan) — manual testing with NVDA/Orca still needed
+**Scope:** All 123 component files in src/components/, supporting engines, tests
+
+## Summary
+
+| Metric | Count | Rating |
+|--------|-------|--------|
+| Components with ariaLabel | 91/123 | Good (74%) |
+| Components with role attributes | 90/123 | Good (73%) |
+| Components with keyboard handlers | 1/123 | Critical gap |
+| Components with tabIndex | 2/123 | Critical gap |
+| aria-live regions | 7 total | Poor |
+| sr-only screen reader text | 1 (skip-links only) | Poor |
+| ariaDescribedBy / ariaLabelledBy | 8 total | Poor |
+| Colour palettes defined | 4 | Complete |
+| Font size presets | 4 (14-20px) | Complete |
+| Focus style options | 4 | Complete |
+| Accessibility engine tests | 30+ | Complete |
+
+## Architecture (Excellent)
+
+PanLL has dedicated accessibility infrastructure:
+- `AccessibilityEngine.res` — theme, palette, animation, font, focus
+- `AccessibilityModel.res` — type-safe state
+- `AccessibilityToolbar.res` — floating FAB widget
+- `FocusDimmingEngine.res` — focus indicator styling
+- `KeyboardUtil.res` — keyboard utilities
+- `accessibility-baseline.k9.ncl` — K9 validator contract
+
+## Critical Gaps
+
+### 1. Keyboard Navigation (Priority 1)
+
+Only 1 of 123 components (MyLang.res) has keyboard event handlers.
+All interactive panels need:
+- Enter/Space to activate buttons
+- Arrow keys for lists/tabs
+- Escape to close overlays
+
+**Remediation:** Add a `KeyboardNav.res` utility module with standard handlers
+that components can compose. Target: all 108 panels keyboard-navigable.
+
+### 2. Tab Order (Priority 1)
+
+Only 2 components use tabIndex. Custom interactive elements are invisible
+to keyboard users.
+
+**Remediation:** Add `Attrs.tabIndex(0)` to all custom interactive elements.
+Add `Attrs.tabIndex(-1)` to programmatically focusable containers.
+
+### 3. Live Regions (Priority 2)
+
+Only 7 aria-live regions across 108+ panels. Status changes, form validation,
+and dynamic content updates are silent to screen readers.
+
+**Remediation:** Add `aria-live="polite"` to status bars, notification areas,
+and VQL result displays. Add `aria-live="assertive"` to error messages.
+
+### 4. Screen Reader Text (Priority 2)
+
+Only 1 sr-only instance (skip-links). Icon-only buttons, data visualizations,
+and status indicators lack text alternatives.
+
+**Remediation:** Add sr-only labels to icon buttons and decorative elements
+that carry meaning.
+
+### 5. Complex Relationships (Priority 3)
+
+Only 8 ariaDescribedBy/ariaLabelledBy instances. Form fields, error messages,
+and complex controls need semantic linking.
+
+## What's Already Working
+
+- 4 colour palettes (Standard, Deuteranopia, Protanopia, High Contrast)
+- Scalable font sizes (14-20px presets, rem-based)
+- Reduced motion detection and respect
+- Focus indicator options (Default, High Contrast, Thick, Dotted)
+- OS theme preference detection (System mode)
+- Floating accessibility toolbar (non-intrusive FAB)
+- 30+ engine-level tests for preference persistence
+
+## DD-008 Compliance
+
+| Level | Criteria | Status |
+|-------|----------|--------|
+| Baseline | ariaLabel + role per component | 90/123 (73%) |
+| Full | Baseline + keyboard + tabIndex | ~3/123 (~2%) |
+| Target | Full + aria-live + sr-only | 0% |
+
+## Next Steps
+
+1. Create `KeyboardNav.res` utility with composable keyboard handlers
+2. Add tabIndex to all custom interactive elements
+3. Add aria-live regions to status-changing areas
+4. Add sr-only labels to icon-only buttons
+5. Manual testing with NVDA/Orca (requires Jonathan)
+6. Update K9 validator to enforce full compliance

src/core/KeyboardNav.res

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+
+/// PanLL KeyboardNav — composable keyboard navigation handlers for panels.
+///
+/// Provides standard keyboard interaction patterns that components can compose
+/// into their event attributes. Follows WAI-ARIA Authoring Practices:
+///   - Enter/Space activates buttons
+///   - Arrow keys navigate lists and tab bars
+///   - Escape closes overlays/modals
+///   - Home/End jump to first/last item
+///
+/// Usage in components:
+///   button(list{
+///     Events.onClick(MyAction),
+///     KeyboardNav.onActivate(MyAction),   // Enter + Space
+///     Attrs.tabIndex(0),
+///   }, list{text("Click me")})
+///
+/// All functions are pure — they return event attributes, not side effects.
+
+open Tea_Vdom
+open Tea_Html
+
+/// Key string constants for readability.
+module Key = {
+  let enter = "Enter"
+  let space = " "
+  let escape = "Escape"
+  let arrowUp = "ArrowUp"
+  let arrowDown = "ArrowDown"
+  let arrowLeft = "ArrowLeft"
+  let arrowRight = "ArrowRight"
+  let home = "Home"
+  let end_ = "End"
+  let tab = "Tab"
+}
+
+/// Dispatch a message when Enter or Space is pressed (button activation pattern).
+let onActivate = (msg: 'msg): attribute<'msg> =>
+  Events.onKeyDown(key =>
+    if key === Key.enter || key === Key.space {
+      Some(msg)
+    } else {
+      None
+    }
+  )
+
+/// Dispatch a message when Escape is pressed (close/dismiss pattern).
+let onEscape = (msg: 'msg): attribute<'msg> =>
+  Events.onKeyDown(key =>
+    if key === Key.escape {
+      Some(msg)
+    } else {
+      None
+    }
+  )
+
+/// Dispatch messages for vertical arrow navigation (list/menu pattern).
+let onVerticalNav = (~onUp: 'msg, ~onDown: 'msg): attribute<'msg> =>
+  Events.onKeyDown(key =>
+    if key === Key.arrowUp {
+      Some(onUp)
+    } else if key === Key.arrowDown {
+      Some(onDown)
+    } else {
+      None
+    }
+  )
+
+/// Dispatch messages for horizontal arrow navigation (tab bar pattern).
+let onHorizontalNav = (~onLeft: 'msg, ~onRight: 'msg): attribute<'msg> =>
+  Events.onKeyDown(key =>
+    if key === Key.arrowLeft {
+      Some(onLeft)
+    } else if key === Key.arrowRight {
+      Some(onRight)
+    } else {
+      None
+    }
+  )
+
+/// Dispatch messages for Home/End navigation (jump to first/last).
+let onHomeEnd = (~onHome: 'msg, ~onEnd: 'msg): attribute<'msg> =>
+  Events.onKeyDown(key =>
+    if key === Key.home {
+      Some(onHome)
+    } else if key === Key.end_ {
+      Some(onEnd)
+    } else {
+      None
+    }
+  )
+
+/// Combined list navigation: ArrowUp/Down + Home/End + Enter to select + Escape to dismiss.
+/// Useful for dropdown menus, comboboxes, listboxes.
+let onListNav = (
+  ~onUp: 'msg,
+  ~onDown: 'msg,
+  ~onHome: 'msg,
+  ~onEnd: 'msg,
+  ~onSelect: 'msg,
+  ~onDismiss: 'msg,
+): attribute<'msg> =>
+  Events.onKeyDown(key =>
+    if key === Key.arrowUp {
+      Some(onUp)
+    } else if key === Key.arrowDown {
+      Some(onDown)
+    } else if key === Key.home {
+      Some(onHome)
+    } else if key === Key.end_ {
+      Some(onEnd)
+    } else if key === Key.enter || key === Key.space {
+      Some(onSelect)
+    } else if key === Key.escape {
+      Some(onDismiss)
+    } else {
+      None
+    }
+  )
+
+/// Helper: make a focusable div container (tabIndex 0).
+let focusable: attribute<'msg> = Attrs.tabIndex(0)
+
+/// Helper: programmatically focusable but not in tab order (tabIndex -1).
+let focusableHidden: attribute<'msg> = Attrs.tabIndex(-1)
+
+/// Helper: screen reader only text (visually hidden but announced).
+let srOnly = (label: string): Tea_Vdom.t<'msg> =>
+  span(
+    list{Attrs.class_("sr-only")},
+    list{text(label)},
+  )
+
+/// Helper: aria-live polite region wrapper (for status updates).
+let livePolite = (children: list<Tea_Vdom.t<'msg>>): Tea_Vdom.t<'msg> =>
+  div(list{Attrs.ariaLive("polite")}, children)
+
+/// Helper: aria-live assertive region wrapper (for errors/alerts).
+let liveAssertive = (children: list<Tea_Vdom.t<'msg>>): Tea_Vdom.t<'msg> =>
+  div(list{Attrs.ariaLive("assertive")}, children)