How kvnq-poza/a11y-live works
Project Type and Purpose
• This is a front-end JavaScript library/application (“A11y Live”) that runs in the browser to provide real-time WCAG accessibility feedback. It bundles a core engine (mutation observer, rule engine, reporter) and a UI layer (overlay, panel, tutorial).
File Structure Analysis
• Top level: HTML entry points (index.html, demo.html), assets (CSS/JS for demos), package.json (npm support), and src folder.
• src/core: engine.js (main class), rules.js (rule definitions), reporter.js (aggregates results)
• src/ui: overlay.js, panel.js, tutorial.js, ui-Manager.js (coordinates UI components)
README Insights
• Core classes: A11yEngine, RuleEngine, Reporter
• UI components: PanelComponent, OverlayComponent, TutorialComponent
• Browser APIs: MutationObserver, IntersectionObserver
• Events: custom DOM events for engine start/stop and violation updates
• Integration methods: direct script include or ES/CJS import
Main Components
a. Core Layer
• A11yEngine
• RuleEngine (holds & executes accessibility rules)
• Reporter (aggregates violations, formats exports)
b. UI Layer
• UIManager (initializes & wires UI components)
• PanelComponent (list & filter violations)
• OverlayComponent (highlights elements)
• TutorialComponent (guided walkthrough)
c. Browser APIs (external services)
• MutationObserver (feeds DOM changes into A11yEngine)
• IntersectionObserver, getComputedStyle, etc.
d. Host Page
• HTML entry point(s)
• User code (integration scripts or modules)
e. Optional Build/Dev Tooling
• package.json → npm scripts (install, start, test)
Relationships and Data Flow
1. Host Page loads engine.js → instantiate A11yEngine
2. A11yEngine
→ registers MutationObserver on target (default document.body)
→ on mutation batch, invokes RuleEngine.test(elementList)
→ collects AnalysisResult objects
→ passes results to Reporter
→ emits custom events (a11y-live-started, violation-found, a11y-live-stopped)
3. UIManager listens to engine events
→ updates PanelComponent (lists violations)
→ commands OverlayComponent to highlight elements
→ manages TutorialComponent lifecycle
4. Reporter can export data (JSON/CSV/HTML) on demand
Architectural Patterns & Design Principles
• Modular separation: core engine vs. UI
• Observer pattern: browser MutationObserver + custom DOM events
• Strategy/Plugin pattern: rules are pluggable objects in RuleEngine
• MVC-like pattern: Engine (Model), UIManager/View components → decoupled via events
• Single responsibility: each module has a clear domain (analysis vs. rendering vs. reporting)
Technologies & Frameworks
• Vanilla ES6 modules (engine, reporter, ui modules)
• Browser native APIs (MutationObserver, IntersectionObserver)
• npm for packaging/testing (Jest)
• CSS/JS for UI overlays and panel styling