Skip to main content

Accessibility Best Practices

This document defines accessibility requirements for documentation and CLI output in this repository. Use it when authoring Markdown files or shell scripts that produce user-facing text.

Scope​

This project applies accessibility best practices to two areas.

AreaWhat the project controls
DocumentationMarkdown files rendered on GitHub and documentation sites
CLI outputShell scripts in deploy/ and scripts/ that emit messages

[!NOTE] Runtime application accessibility (screen reader support, WCAG UI compliance) is outside the scope of this infrastructure-focused repository. If the project adds a web UI or desktop component in the future, revisit this page and expand coverage.

Documentation Accessibility​

All Markdown files follow these conventions, which are enforced by markdownlint (MD045, MD001) and PR review.

  • Provide descriptive alt text for every image (![Alt text](path))
  • Follow heading hierarchy without skipping levels (H1 → H2 → H3)
  • Use descriptive link text instead of raw URLs or "click here"
  • Use tables and lists for structured data rather than dense paragraphs
  • Use GitHub alerts (> [!NOTE], > [!WARNING]) for important callouts
  • Provide text equivalents for any diagrams or visual content

Alt Text Guidelines​

Alt text describes the content and purpose of an image.

Image TypeAlt Text Approach
Architecture diagramSummarize components and data flow shown
ScreenshotDescribe the UI state and highlighted element
Logo or badgeState the badge name and status
Decorative imageUse empty alt (![](path)) only when truly decorative

CLI Output Accessibility​

Shell scripts support the NO_COLOR standard. When the NO_COLOR environment variable is set (any value), scripts suppress ANSI color codes so output works with screen readers and log aggregators.

Run any deployment script without color:

NO_COLOR=1 ./infrastructure/setup/01-deploy-robotics-charts.sh

Implementation Pattern​

Shared color functions in scripts/lib/common.sh check NO_COLOR before emitting escape sequences:

if [[ -z "${NO_COLOR+x}" ]]; then
  info()  { printf '\033[1;34m[INFO]\033[0m  %s\n' "$*"; }
  warn()  { printf '\033[1;33m[WARN]\033[0m  %s\n' "$*" >&2; }
  error() { printf '\033[1;31m[ERROR]\033[0m %s\n' "$*" >&2; }
else
  info()  { printf '[INFO]  %s\n' "$*"; }
  warn()  { printf '[WARN]  %s\n' "$*" >&2; }
  error() { printf '[ERROR] %s\n' "$*" >&2; }
fi

Generated Artifacts​

Automated pipelines, Terraform plans, and Helm chart outputs are out of scope. Accessibility standards apply only to human-authored content committed to the repository.

OpenSSF Compliance​

This page, combined with markdownlint enforcement (MD045, MD001) and NO_COLOR support in deployment scripts, satisfies the OpenSSF Best Practices Silver criterion accessibility_best_practices:

The project MUST include a statement about software accessibility in its documentation, addressing at minimum accessibility of the documentation itself and software output.