Accessibility

This page documents the accessibility system built into fork-sync-all and propagated to all infra-core and upstream-sync consumer repos.

What the system does

Every repo in the OSP stack is audited for accessibility on every push to main and weekly via check-accessibility.yml. The audit covers five layers:

Accessibility artifacts

Each repo that has run check-accessibility.yml will have these files committed to its default branch:

Running the audit

On push: automatically triggered when README.md or CODEOWNERS changes.

Weekly: runs every Monday at 04:17 UTC.

Manually:

# Via GitHub CLI
gh workflow run check-accessibility.yml

# With options
gh workflow run check-accessibility.yml \
  -f repo=my-repo \
  -f fail_on_error=true

Locally (requires espeak-ng, python3-louis, pa11y):

sudo apt-get install espeak-ng ffmpeg python3-louis liblouis-data
npm install -g pa11y github-codeowners

REPO_DIR=. OWNER=my-org REPO=my-repo \
  AUDIO_ENABLED=true BRAILLE_ENABLED=true WCAG_ENABLED=true \
  bash scripts/check-accessibility.sh

Installing the runner dependencies

The check-accessibility.yml workflow installs these automatically on the GitHub Actions runner. For local use:

# Ubuntu / Debian
sudo apt-get install espeak-ng ffmpeg python3-louis liblouis-data

# macOS (Homebrew)
brew install espeak liblouis ffmpeg
pip3 install louis

# Node tools
npm install -g pa11y github-codeowners

CODEOWNERS coverage

Ownership coverage is measured by github-codeowners audit. Thresholds:

To see unowned files:

cd <repo>
github-codeowners audit -u

To validate your CODEOWNERS file:

github-codeowners validate

README accessibility standards

The README scan checks for:

• Missing alt text — every ![]() image must have descriptive alt text
• Non-descriptive links — avoid [click here], [here], [link], [read more]
• Table headers — every markdown table must have a |---|---| separator row
• Bare URLs — wrap URLs in descriptive link text: [description](url)
• Reading level — avg sentence length ≤ 20 words is accessible; > 30 is flagged
• H1 heading — every README must start with a # Title

WCAG 2.1 AA compliance

HTML docs in DOCS/generated/ are scanned with pa11y against the WCAG 2.1 AA standard. Common issues:

Audio overview

README.audio.mp3 is generated by espeak-ng, a lightweight open source TTS engine. The README is stripped of markdown syntax before synthesis for cleaner output.

Playback:

# Any media player
mpv README.audio.mp3
vlc README.audio.mp3

# Command line
ffplay README.audio.mp3

Braille output

README.brl is generated by liblouis, the standard open source Braille translation library used by NVDA, JAWS, and VoiceOver. Output is Unified English Braille (UEB) Grade 2.

To display on a Braille terminal:

# Most Braille displays accept .brl files directly via their driver software
# On Linux with brltty:
brltty -f README.brl

Upstream tools tracked

All accessibility tools are forked into Interested-Deving-1896 and mirrored to the accessibility_deving GitLab subgroup:

Further reading

• WCAG 2.1 Quick Reference
• GitHub ReadME Project — Accessibility
• Coding accessibility: Building autonomy with AI
• NVDA: Software by the blind, for the blind
• WebAIM: Introduction to Web Accessibility
• Deque University — axe-core rules
• NV Access — the non-profit behind NVDA