Accessibility

Red Glare inherits the USWDS accessibility baseline — built on WCAG 2.1 AA. The integration ships with correct markup, focus management, keyboard navigation, and ARIA labels for every component it provides. Authoring still matters — accessibility is partly what you write.

What the integration does for you

Every page renders a hidden "Skip to main content" link that appears on keyboard focus. Links the user directly to <main id="main-content">, past the government banner, header, and nav.

Semantic landmarks

<header>, <nav>, <main>, <aside> (for the sidebar and TOC), <footer>, and <section> (for the identifier) are all present. Assistive tech can jump between regions.

Heading hierarchy

Each page has one <h1> (from frontmatter title). Authored ## / ### / #### preserve their levels — the TOC, deep linking, and slug generation all respect the outline as you author it.

Focus management

Tabs and code groups implement the WAI-ARIA Authoring Practices tabs pattern — arrow keys navigate, Home/End jump, only the active tab is in the tab order. Accordions wire aria-expanded / aria-controls correctly. Every button has a type.

Color contrast

Default USWDS tokens meet WCAG AA on body text and interactive elements. If you override tokens via uswdsSettings, re-verify contrast for your chosen palette.

What you still need to do

Author-side checklist

Write meaningful alt text for every image.
Describe link destinations in the link text, not "click here".
Use real headings, not bold paragraphs, for section titles.
Keep heading levels sequential — don't skip from ## to ####.
For alerts and summary boxes, always include the #heading slot with a real markdown heading.
For language switching, set i18n.lang in frontmatter.

Testing

Automated

Run an accessibility checker against a built site. The two battle-tested options:

axe-core via Playwright, Puppeteer, or the Chrome extension.
WAVE browser extension.

Both catch common issues — missing alt text, skipped heading levels, insufficient contrast, unlabeled form fields — and neither replaces manual review.

Manual

Keyboard-only walkthrough. Tab through every page. Every interactive element should be reachable, visible when focused, and activatable with Enter/Space.
Screen reader pass. VoiceOver (Mac) or NVDA (Windows). Listen to a page top to bottom. Regions should be announced with their names; images should have meaningful descriptions; code blocks should be readable.
Zoom to 200%. Content should reflow without horizontal scrolling.

Limitations

Color contrast is only enforced for USWDS defaults. Custom theming via uswdsSettings can introduce contrast failures; re-test after theming changes.
Math accessibility relies on KaTeX. Complex equations render with KaTeX's built-in accessibility; screen readers announce equations linearly. For high-stakes content (exams, legal text), consider providing a text-only fallback.
Third-party embeds are your responsibility. If you embed a YouTube video, a CodePen, or similar, meet the accessibility bar yourself — the integration doesn't inspect embed content.

Found something that regresses the baseline? File an issue on the repo tagged accessibility. Include the page URL, the assistive tech you're using, and the expected behavior.