Accessibility Audit 2026: Systematic Review of Hubs Documentation

[HussainAther]

Title

Accessibility Audit 2026: Systematic Review of Hubs Documentation

---

What?

Create a structured accessibility audit of the Hubs Documentation site to ensure consistency with:

• Screen reader compatibility (NVDA testing has already been partially done)
• Heading hierarchy correctness
• Proper alt text usage on all images and videos
• Callout contrast and semantic clarity
• List formatting consistency
• Link clarity and descriptive anchor text

This would be tracked as a checklist-based audit across all major docs sections.

---

Why?

Accessibility has been discussed multiple times in documentation meetings, including:

• Screen reader testing (NVDA)
• Bolding/italics behavior
• Callout formatting
• Accessibility policy PR work

Rather than addressing accessibility piecemeal, this issue proposes a structured, systematic audit to:

• Reduce future regressions
• Improve usability for all users
• Make documentation more contributor-friendly
• Align with open-source best practices

This also creates a clear entry point for new contributors looking for meaningful but bounded work.

---

Scope

This audit would:

1. Create a tracking checklist (either in this issue or linked sub-issues)

2. Review all top-level docs pages

3. Identify and log:

   • Missing alt text
   • Improper heading nesting (e.g., jumping from H2 → H4)
   • Non-descriptive links (“click here”)
   • Overuse of bolding/italics where semantic markup should be used
   • Callout color misuse or inconsistent formatting

4. Submit targeted PRs in small batches

---

Proposed Audit Checklist

For each page:

• All images include descriptive alt text
• Videos include captions or descriptive context
• Heading levels are hierarchical and consistent
• Links use descriptive anchor text
• Callouts use standardized syntax
• Color usage does not rely on color alone for meaning
• Lists are formatted consistently and accessibly
• UI elements are described clearly (capitalization/formatting consistent)

---

Deliverables

• Initial tracking checklist committed to repo (or maintained in issue)
• Series of small, focused PRs
• Final summary comment once audit complete

---

Out of Scope (For Now)

• Full redesign of documentation structure
• Docusaurus version upgrade
• Major content rewrites
• Policy changes outside documentation repo

---

Suggested Labels

• documentation
• accessibility
• good first issue
• roadmap

---

If approved, I’m happy to take the first pass on drafting the tracking checklist and beginning with the Beginner’s Guide section.

[HussainAther]

What?
Improves accessibility by replacing vague link text (e.g., "this section", "later sections")
with descriptive link text and clarifying some image alt attributes.

Why?
Improves screen reader navigation and documentation clarity.

Scope
Minor wording updates only. No functional or structural changes.