All features are opt-in via controllers, use native buttons, support Enter/Space and ordinary Tab order, and expose pressed/disabled state or a polite numeric output. Defaults leave the host unchanged. Values persist once changed and return to defaults on Reset All. Effects persist when controls/panel disappear and are cleaned on provider removal. Widget portals are excluded. The engine restores prior inline properties and priorities instead of simply deleting them.
| Controller / key | Default; states and bounds | Host behavior / edge cases |
|---|---|---|
| TextScaleController / fontScale | 1.0; 1.0, 1.125, 1.25, 1.5, 2.0 (stepwise) | Reflow-safe stepwise text enlargement without CSS transforms or compounding. Protects forms, labels, code, icons, widget, and exempt content. |
| FontSizeController / fontSize | 100; 50–200%, step 10 or stepwise | Scales computed font size and line height together. Supports optional stepScale / steps props; protects forms, labels, code blocks, icons, and widget UI. |
| LineHeightController / lineHeight | 100; 50–200%, step 10 or stepwise presets | Scales computed line height. Supports stepPresets (100%, 150%, 175%, 200% / 1.0x, 1.5x, 1.75x, 2.0x) and custom steps. Excludes tables, code blocks, controls, and widget UI. |
| LetterSpacingController / letterSpacing | 0; 0–10px, step 1 | Sets letter spacing on content elements. Protects cursive/Arabic/RTL scripts (disabled) and Indic/Sinhala/Tamil scripts (clamped <=1px). Excludes tables, code, and controls. |
| WordSpacingController / wordSpacing | 0; 0–10px, step 1 | Sets word spacing on content elements while protecting tables, code, controls, and widget UI. |
| ParagraphSpacingController / paragraphSpacing | 0; 0–32px, step 4 | Increases paragraph bottom margin (p, [role="paragraph"]) while protecting tables, code, and controls. |
| ContrastController / contrast | 0; 0/1/2/3, light, dark, high, invert, reduced, named palettes | Off, 1.25×, 1.5×, 2×; reduced=0.5×. Semantic light, dark, high contrast, and invert tokens protect images/video/SVG/charts and validation states. Bypasses overrides when OS forced-colors is active. |
| ContrastModeController / contrastMode | off; off/light/dark/high/invert | Semantic light, dark, high contrast, and media-safe invert modes. Preserves images, charts, and validation errors. Native forced-colors protection. See docs/CONTRAST.md. |
| SmartContrastController / smartContrast | off; off/aa/aaa (or false/true) | Opt-in measured smart contrast research prototype. Evaluates foreground relative luminance against computed backdrop without layout thrashing; blends semi-transparent ancestor layers; reports unsupported gradients/images; restores styles on reset. See docs/SMART_CONTRAST.md. |
| SaturationController / saturation | 0; 0/1/2/3, "original"/"low"/"high"/"grayscale" | Off, 0.2× (Low), 2× (High), and Grayscale modes. Composes with other filters. Features accessible chart/image advisory warnings and forced-colors bypass. See docs/SATURATION_AND_GRAYSCALE.md. |
| InvertColorsController / invertColors | false; boolean | Adds invert(1), includes content images. |
| GrayscaleController / grayscale | false; boolean | Adds grayscale(1) monochrome mode. Displays accessible visualization advisory warning and respects OS forced-colors. See docs/SATURATION_AND_GRAYSCALE.md. |
| LinkHighlightController / linkHighlight | false; false/true/underline/palettes | Non-color underline cues (2px thickness, 3px offset) and high-contrast palettes. Preserves disabled links and system LinkText in forced colors. See docs/LINKS_AND_FOCUS.md. |
| HighlightFocusController / highlightFocus | false; boolean | High-visibility dual-ring focus outline (3px blue + 5px white halo) with forced-colors Highlight support. Preserves disabled controls. See docs/LINKS_AND_FOCUS.md. |
| SkipToMainLink / findMainLandmark | Dynamic helper / link | Authentic skip-to-main landmark link. Only renders when a real <main> or [role="main"] exists. Transfers focus and scrolls into view. See docs/LINKS_AND_FOCUS.md. |
| TextAlignController / textAlign | default; default/left/center/right/justify | Scoped strictly to logical text blocks (p, headings, lists, blockquotes); excludes tables, form controls, and code. Justification displays an accessible WCAG SC 1.4.8 advisory warning. |
| FontFamilyController / fontFamily | default; default/legible/dyslexia-option | Applies clean system-ui or OpenDyslexic with Sinhala/Tamil fallbacks. Code blocks, icons, and SVGs are protected. See docs/FONTS.md. |
| HideImagesController / HideDecorativeImagesController / hideImages | false; boolean | "all" | "decorative" | HideImagesController (default mode="all") hides host img/picture/object/embed/decorative <svg> and CSS-based images (background-image, background shorthand, var(...), image-set(), ::before/::after, html/body, list-style-image, content: url()). HideDecorativeImagesController (and mode="decorative") restricts hiding to decorative images only. Protects widget UI, interactive controls, icon-only links, CAPTCHA, charts, maps, QR codes, math, and pure CSS gradients. See docs/DECORATIVE_IMAGES.md. |
| HideVideosController / hideVideos | false; boolean | Hides video and recognized YouTube/Vimeo embed URL patterns. Does not hide unrelated iframe documents, pause video or mute audio. |
| ReduceMotionController / reduceMotion | false; boolean | Scoped CSS animation and smooth-scroll suppression, tracked WAAPI animation pausing, and explicit media autoplay pause. Honors OS prefers-reduced-motion. See docs/REDUCE_MOTION.md. |
| BigCursorController / bigCursor | false; boolean | 40px high-contrast pointer via SVG cursor with native fallback. Capability-aware: detects (pointer: fine) and suppresses styles on touch-only hardware. Host CSS cursor effects are restored. See docs/READING_AIDS.md. |
| ReadingMaskController / readingMask | false; boolean / number (height) | Transparent reading aperture window with surrounding screen dimmed. Adjustable height (default 100px, 40–400px), stepper controls, pointer/touch/focus/scroll tracking, Alt+Up/Down nudging, Escape dismissal. See docs/READING_AIDS.md. |
| ReadingGuideController / readingGuide | false; boolean | 4px blue line with white border. Pointer-transparent (pointer-events: none !important), never blocks clicks/selection/focus. Follows pointer, touch drag, keyboard focus, and scroll. Alt+Up/Down nudging, Escape dismissal. See docs/READING_AIDS.md. |
| TooltipsController / AccessibleTooltipsController / tooltips | false; boolean | Displays authored descriptions (aria-description, aria-describedby, aria-label, alt, title) on hover and focus. Strictly excludes sensitive/password fields. WCAG 2.1 SC 1.4.13 compliant (Escape dismissal, hoverable, persistent, viewport clamped). See docs/TOOLTIPS.md. |
| PageNavigatorController / HeadingsNavigatorController / PageStructureController | Action dialog; no persistent preference | Scans real DOM headings (h1–h6) and named landmarks (banner, navigation, main, region, etc.). Safe scroll and focus with temporary tabindex cleanup, live mutation updates without loops, and search filtering. See docs/PAGE_NAVIGATOR.md. |
| ProfilesController / ProfileController / AccessibilityProfilesController | activeProfile; ProfilePresetId / null | Previews, applies, and reverts eight neutral presets (Motor, Blind, Color Blind, Dyslexia, Low Vision, Cognitive, Seizure, ADHD). Follows deterministic override model where user explicit choices survive reversal. Zero implicit audio/mic. See docs/PROFILES.md. |
| PresetsController / CustomPresetsController / SettingsImportExportController | customPresets; CustomPreset[] | Saves named user presets, 1-click apply/delete, and versioned JSON backup and transfer. Strict privacy exclusions discard private data, transcripts, and credentials. Saved presets library survives display reset. See docs/PRESETS.md. |
Locales & i18n (en, si, si-LK, ta, ta-LK) |
LocaleStrings / locale prop |
Reviewed English, Sinhala, and Tamil locale packs with typography fallbacks and full RTL infrastructure. Automatic document.documentElement.lang resolution; host content is never translated. See docs/LOCALES.md. |
| ReadingModeController / readingMode | false; boolean | Non-destructive article extraction into an accessible overlay dialog. Preserves headings, links, images, and alt text while stripping forms, navigation, and sensitive fields. Supports Light/Sepia/Dark themes and zoom. See docs/READING_MODE.md. |
| KeyboardShortcutsController / shortcutsEnabled / customShortcuts | false; boolean / Record<string, string> | Discoverable shortcut cheat sheet, conflict-checked remapping, reserved browser protection (Ctrl+U, Ctrl+R), form suppression, and Link Explorer with uninformative text detection. See docs/KEYBOARD_SHORTCUTS.md. |
| ReadAloudController / readAloud / readAloudRate / readAloudPitch / readAloudVoice | false; 1.0; 1.0; null | User-initiated client-side text-to-speech read-aloud via Web Speech API (speechSynthesis). Sentence-level chunking, pause/resume/stop, voice selection, rate and pitch steppers, Escape dismissal, sensitive/form field exclusions, and zero network transmission. See docs/READ_ALOUD.md. |
| DictionaryController | Action dialog; no persistent preference | Accessible terminology dictionary and provider interface. Explicit user action lookup, 100% offline local static glossaries (English, Sinhala, Tamil), zero network transmission by default, truthful non-hallucinating responses, sensitive data rejection, and focus restoration. See docs/DICTIONARY.md. |
| VoiceNavigationController / voiceNavigation | false; boolean | User-initiated speech recognition navigation research prototype using native Web Speech API. Recognizes explicit commands (open, close, next/prev/first heading, scroll down/up/top/bottom, stop, help). Features 30s silence timeout, background tab auto-stop, zero audio storage, and full keyboard alternatives. See docs/VOICE_NAVIGATION.md. |
| FeatureMenu / menuConfig | MenuCustomizationConfig; customizable | Declarative per-site feature menu reordering, grouping, custom labels, suggested defaults, non-crashing safe diagnostics, and memoized stable rerenders. See docs/MENU_CUSTOMIZATION.md. |
| ResetController | No feature state | Clears display settings including custom/unmounted controls, preserves widget placement; runs legacy reset callbacks; keeps panel open. |
The library exports modular UI primitives conforming to WCAG 2.2 criteria:
| Primitive | Accessible Role & State | Key Capabilities |
|---|---|---|
ToggleControl |
role="switch", aria-checked |
Keyboard Space/Enter toggle, disabled/unavailable states, >=44px touch targets (>=48px in largeControls mode). |
ChoiceControl |
role="radiogroup", role="radio", aria-checked |
Arrow key (Left/Right/Up/Down/Home/End) cycling, check indicators, multi-level/category grouping. |
StepperControl |
role="group" with <output aria-live="polite"> |
Accessible increment/decrement buttons, boundary clamping, optional role="slider" range input. |
FeatureCard |
role="group", aria-label |
Card container with title, icon, description, status badge, and alert states (idle, active, error, unavailable, permission-required). |
SearchCount |
role="status", aria-live="polite" |
Live status announcement of matched and total features for search filtering. |
EmptyState / ErrorState |
role="status" / role="alert" |
Clear messaging with action button for empty results and error recovery. |
ProfilePreviewCard |
role="group" |
Previews affected settings for accessibility profiles (low-vision, dyslexia, etc.) and provides one-click reversal back to custom settings. |
Reference: vanilla 47f44c5 (accessibility-menu.js, package 1.2.2); older React 7aef17c; newer baseline 6dfbd44. “Present” is source evidence, not proof of correctness. See baseline for defects.
| Original behavior | Older React | Newer baseline | Stabilized behavior |
|---|---|---|---|
| Invert + grayscale | Exclusive contrast enum | Independent but overwrite | Independent, composable |
| Low 20% / high 200% saturation | Exclusive modes | 50% / 200%, overwrite | Restore original 20% / 200% |
| Contrast 0.5 / 1.5 / 2 | Replaced by named palettes | 1.25 / 1.5 / 2 | Preserve newer levels, add reduced 0.5 and older palettes |
| 3 link palettes | One highlighting toggle | One toggle | Default toggle plus all 3 original palettes |
| Font size 1.3/1.5/1.8rem on html | Root scale | 50–200% on html | Fine-grained computed font scaling, including px fonts |
| Line height 1.5/1.8/2 on descendants | Root inherited value | Root percent | Scale actual computed line height across descendants |
| Letter spacing .1/.2/.3rem | em slider | 0–10px root | 0–10px descendant override |
| Left/center/right text alignment | Includes initial | Left is “off” | Explicit default plus left/center/right/justify |
| Hide img / video with display:none | Images only | Images/videos plus some embeds | Both; retain layout, restrict video embeds |
| Circle cursor enlarges on link hover | Big cursor | Static circle CSS cursor | Large contrast pointer; decorative hover enlargement replaced |
| Reading mask clear center | Guide only | Dark strip obscures center | Clear center restored |
| Quarter-width guide + triangle | Guide | Full-width line | Full-width line; native cursor retained |
| Reset classes, sizes, counters | Fixed state reset | Generic reset, stale timer | Generic reset, cancellation and effect restoration |
| Four user-selected placements, saved | Draggable trigger | Position prop, broken panel positioning | Persisted free drag, four corners, Alt+arrow and click controls |
| Save on beforeunload, unguarded parse | No localStorage persistence | Debounced but shared timer | Versioned/validated, per-owner debounce, pagehide/unmount flush |
Widget placement is now a persisted preference with pointer dragging and non-drag alternatives. The initial position prop remains a fallback. Original cursor decoration remains deferred, not counted as visual parity. Original combinations enumerated CSS selectors; centralized composition avoids that unmaintainable combinatorial model. Original click-only div controls are replaced with native named buttons.
tests/features.test.tsx: stepper bounds, palettes, all alignment states, boolean effects, combined filters, native host restoration and dynamic routes. tests/plugin.test.tsx: custom lifecycle, restoration, invalid data, focus, Strict Mode, SSR, hydration, singleton enforcement. tests/storage.test.ts: deterministic timers, errors and schema envelopes. tests/browser/widget.spec.ts: actual compiled CSS, packed consumers, visibility, pointer interaction, geometry, keyboard and axe. See project status for executed results and manual gaps.
The integration diagnostics suite (runDiagnostics, DiagnosticsHarness, useDiagnostics) performs non-invasive environment, DOM, and styling checks during development:
- Provider & Widget Placement: Diagnoses multiple providers and identifies ancestor containing-block traps (
filter,transform,perspective). - Storage Boundaries: Tests
localStorage/sessionStorageaccessibility, quotas, and sandbox restrictions with graceful in-memory fallback. - CSP & Style Injection: Tests dynamic
<style>injection and CSS custom property support against restrictivestyle-src. - Host CSS Conflicts: Detects extreme host
z-index >= 2,147,483,000and root scroll locks (overflow: hiddenon bothhtmlandbody). - DOM & Landmark Structure: Scans for
<main>landmarks,<h1>titles, skipped heading levels, and unlabelled content<img>tags (privacy-safe, no sensitive URLs or PII). - Boundaries: Flags embedded
<iframe>elements (cross-origin styling boundaries) and custom elements withShadowRoot. - Zero Compliance Claims: All reports carry an explicit disclaimer stating that automated diagnostics do not constitute official WCAG certification or replace manual audits.
The optional lifecycle callback (onFeatureEvent on <AccessibilityPlugin>) provides local, in-memory event notifications for host application telemetry:
- Strictly Opt-In: Disabled by default; zero events or network requests are emitted unless an explicit listener callback is supplied.
- Reviewed Payloads: Emits coarse event types (
feature-change,feature-reset,panel-toggle,placement-change,profile-apply,preset-apply) with scalar values and canonical feature IDs. - Strict Privacy Exclusions: Never includes page text, user text selections, form inputs, emails, user IDs, cookies, device fingerprints, or Web Speech transcripts/audio recordings.
- Sanitized and Frozen: All payloads are validated against an allowlist and deep-frozen (
Object.freeze). - Resilient: Exceptions thrown in consumer listeners are safely caught and silenced, ensuring application functionality is never interrupted.
The Smart Contrast Research Prototype (SmartContrastController, evaluateSmartContrast, applySmartContrast) dynamically evaluates and enhances text contrast ratios using WCAG relative luminance algorithms and alpha compositing:
-
Mathematical Luminance & Compositing: Evaluates background luminance by traversing parent hierarchies and alpha-compositing semi-transparent backgrounds (
compositeRgba) against the viewport root. -
Configurable Contrast Targets: Supports
off,enhanced(targeting 4.5:1 for normal text, 3:1 for large text$\ge 18\text{pt}$ or bold$\ge 14\text{pt}$ ), andmaximum(targeting 7:1 for normal text, 4.5:1 for large text). - Graceful Unsupported Handling: Transparently flags and skips unsupported complex elements (background images, CSS gradients, complex filters, canvas/video backdrops) while providing live diagnostic statistics.
-
Strict Non-Destructive Restoration: Records original inline colors before enhancement; restores every element back to authored styles immediately upon toggle OFF, mode switch, or
Reset All. -
Zero WCAG Overclaim: Prominently labeled with a
Prototypebadge and disclaimer (SMART_CONTRAST_DISCLAIMER) stating mathematical calculations do not certify official WCAG compliance.
The Voice Navigation Research Prototype (VoiceNavigationController, createVoiceNavigationSession) provides user-initiated speech control for page navigation:
- Local Speech Recognition: Leverages client platform Web Speech Recognition API with zero external network transmission.
- Strict Privacy Guarantees: Zero recording or audio persistence in
localStorage,sessionStorage, or cookies; interim/final transcripts are purely transient in component memory. - Inactivity Watchdog: Automatically shuts down listening after 30 seconds of silence to prevent open background microphones.
- Background Tab Protection: Automatically stops speech recognition when
document.hiddenbecomes true. - Accessible Keyboard Alternatives: Full set of native buttons for heading navigation and scrolling; 100% operational in unsupported browsers or upon permission denial.
- Reduced Motion Respect: Automatically disables smooth scrolling in favor of instant jumps when reduced motion preferences are detected.
The Host-Content Translation Adapter Architecture (TranslationController, translateHostContent) provides a privacy-first, decoupled bridge for translating arbitrary host application text:
- Decoupled from Widget Localization: Clear separation between bundled static widget strings (
src/core/i18n/) and host content translation. - Provider Interface Boundary: Pluggable
TranslationAdapterinterface specifying data retention, residency, and privacy policies. - Explicit User Consent: Strictly user-initiated; requires explicit acknowledgment via consent modal before transmitting host document text.
- Strict Sensitive Content Exclusion: Automatically detects and ignores form passwords, credit card/CVC fields, personal email/phone inputs, technical code blocks (
<code>,<pre>), media boundaries (<iframe>,<svg>), opt-out attributes ([translate="no"]), hidden nodes, and the widget itself. - Cross-Origin & iframe Safeguard: Strictly excludes all
<iframe>elements to protect Same-Origin Policy (SOP) boundaries. - XSS & DOM Injection Prevention: Translated text is strictly assigned via
Text.textContent, neverinnerHTML. - Clean Synchronous Restoration: Synchronous
restore()callback resets modified text nodes back to original host strings immediately. - Offline Mock Translation Adapter:
createOfflineMockTranslationAdapteroperates locally with zero network calls for testing and development.