Accessibility

Accessibility: Inclusive Design for Compitum Docs and Outputs

Quick-Scan Infobox

Aspect	Details
Target User	Educators, developers, and users with diverse needs; no accessibility expertise required.
Core Goal	Ensure Compitum's docs, traces, and visuals are usable by all—screen readers, color-blind users, keyboard navigators.
Time to Audit	5 mins: Scan a page with a tool like WAVE or Lighthouse.
Key Analogy	Like a well-lit classroom: Paths clear for everyone, no one left in the shadows.
Compliance Baseline	WCAG 2.1 AA; evolving with user feedback.

Core Principles Layer (Technical Backbone)

Compitum's accessibility embeds WCAG guidelines into every output layer—from markdown docs to JSON traces and plotted reports. This isn't bolted-on; it's woven into the router's design for mechanistic inclusivity:

• Semantic Structure: Headings (H1–H6) form a logical hierarchy; links use descriptive anchors (e.g., [RouterBench integration](Integration-Guide.md) over "click here").
• Visual Encoding: Plots default to color-agnostic markers (circles, squares) and linestyles (solid, dashed); enforced via matplotlib/seaborn params in src/compitum/plotting.py.
• Multimedia Handling: All images/videos include alt text (e.g., "Utility components bar chart: quality highest at 0.8") and captions; auto-generated where possible via docstring parsing.
• Navigation Aids: Full keyboard support (tab-focusable elements); high-contrast themes (min 4.5:1 ratio) via CSS vars in the docs site.
• Data Outputs: JSON schemas are flat, labeled, and ARIA-compliant for screen readers—e.g., traces use human-readable keys like "utility_components": {"quality": "Predicted score (+ direction)"}.

Why embed? Like bounded observers in quadratic space, constraints here prevent "overload" for users: feasible paths for all, no infeasible exclusions.

Tech Dive: Enforcing in Code (Collapsible for Implementers)

[Notebook content will be embedded by CI]

Pro Tip: Run pytest -m accessibility to validate outputs—flags violations like missing alts.

Approachable Layer (Relatable Hooks for Educators)

Picture Compitum docs as a shared lesson plan: No one should strain to follow the flow. We've ditched the "one-size-fits-most" trap—think of it like adapting a group activity for varying paces, where visual cues (colors) are just one tool, not the only one.

• Classroom Tie-In: For a boundary diagnostics lesson, use linestyles to show utility gaps—ensures color-blind students track "high entropy" lines as easily as dashed vs. solid.
• Analogy Echo: Like a reliable trail map (no faded ink), our JSON traces read aloud cleanly: "Feasible: true; Shadow prices: [0.2, 0.0]"—no cryptic abbreviations.
• Common Hurdle: Overlooked alts? That's the "invisible wall"—our pre-commit hooks catch it, keeping the path open.

Quick-Reference Toolkit (Audit Checklist)

Feature	Check	Tool/Command	Expected Outcome
Headings & Links	Descriptive, hierarchical.	markdownlint --rule MD033,MD034	No "empty" links; outline forms TOC.
Visuals	Markers/linestyles over color-only.	pytest -m plotting	Plots pass color-contrast sim (e.g., via colorspacious).
Multimedia	Alt text + captions.	Manual: Add via 	Screen reader: "Image: [desc]. Caption: [text]."
Navigation	Keyboard/high-contrast.	Browser: Tab through; Lighthouse audit.	Score >90/100; no focus traps.
JSON Outputs	Labeled, flat schema.	`jq '.	keys'` on trace.json

Gotchas Table (Collapsible: Quick Fixes)

Issue	Symptom	Fix	Analogy
Missing Alt	Image loads but silent on reader.	Add .	Forgetting name tags—everyone's a stranger.
Low Contrast	Text blends on dark mode.	Use tools like WebAIM checker; bump ratios.	Dim hallway light—squinting steals focus.
Nested JSON	Deep objects confuse parsers.	Flatten in schema: Use arrays for components.	Tangled yarn—unwind for easy pull.

Next Steps: Your Loop

• Audit a Page: Grab and run a quick Lighthouse pass—spot gaps?
• Feedback Channel: Issues labeled "a11y" on GitHub; or tweak ACCESSIBILITY.md in-repo.
• Deeper Read: Full guidelines in the repo's ACCESSIBILITY.md; ties to Philosophy on equitable signals.

See also: Glossary for terms like "ARIA"; Roadmap for upcoming voice-mode integrations.