Accessibility

How aardvark sites meet WCAG 2.1 AA — landmarks, keyboard navigation, and a build-time contrast check.

Every site aardvark generates targets WCAG 2.1 Level AA out of the box. The chrome ships with semantic landmarks, a skip link, visible keyboard focus, screen-reader announcements, and reduced-motion support — and the build flags color-contrast problems in your theme before they reach readers.

Standards we follow

• WCAG 2.1 Level AA — the contrast, keyboard, and name/role/value success criteria.
• Keyboard-first — every interactive control is reachable and operable without a mouse.
• Screen-reader friendly — landmarks, current-state cues, and a live region for dynamic updates.
• Respects user preferences — prefers-reduced-motion and prefers-color-scheme.

Built-in accessibility features

• Skip to content — the first Tab stop on every page jumps past the header and navigation straight to the main content.
• Landmark regions — the banner, the section tabs, the documentation sidebar, the breadcrumb trail, the main content, and the “On this page” list are each exposed as a labelled region, so screen-reader users can jump between them.
• Visible focus — every link, button, and control shows a clear focus ring when you navigate with the keyboard.
• State cues — the current page (sidebar), the current section (on-this-page), the in-view API operation (sidebar), expanded/collapsed sections, and sorted table columns are announced, not just shown with color.
• Live announcements — filtering a table announces its result (“No matching rows”) to assistive technology.
• API response examples — the API reference shows a response’s example body as a collapsible JSON tree; its expand/collapse-all and copy controls are standard focusable buttons, so a keyboard user can expand and copy the whole body without a mouse. No new keyboard shortcut is introduced, and without the optional viewer it falls back to a plain code block.
• Links beyond color — body links are underlined, so they’re distinguishable without relying on color.
• Reduced motion — scroll-spy, tab, and reveal animations are disabled when your system asks to reduce motion.
• Password unlock form — a password-protected page’s unlock prompt is a real labelled <form>: it’s fully keyboard-operable (the field autofocuses, Enter submits), shows a visible focus ring, and announces a wrong-password message through an aria-live region. No new keyboard shortcut is introduced.
• Taxonomy listing filters — a taxonomy listing’s tag badges are keyboard toggles (Enter/Space, with aria-pressed state), a knowledge base’s category cards are real buttons with the same pressed cue, and the knowledge base announces an active filter’s result count through a status region. Filter state mirrors into the URL hash so a filtered view can be linked and shared; knowledge-base category picks push a history entry, so Back restores the previous filter state there. No new keyboard shortcut is introduced.

Keyboard shortcuts

The chrome and the interactive components are fully keyboard-operable:

Build-time contrast check

The build reads your theme’s palette from theme.scss, checks it against WCAG AA, and prints a non-fatal warning for any text/background pair that falls short — in both light and dark:

aardvark: warning — color contrast below WCAG AA:
  light — links: #8a7fff on #ffffff = 3.41:1 (needs 4.5:1)
  Adjust the colors in your theme's theme.scss so each pair meets the ratio
  (a darker/lighter shade per scheme), or set a11y.contrast: false to silence this.

It checks body text, secondary text, links, the active navigation item, text on the code/table surface, and the table header. Because each scheme has its own background, pick a $primary (and the other variables) that reads well on both — that’s why this site uses a lighter primary in dark mode than in light. Tune the check in aardvark.config.yaml:

a11y:
  contrast: true        # run the audit (default: true; non-fatal warnings only)
  contrastLevel: AA     # AA (default) or AAA
# a11y: false           # shorthand to turn the audit off entirely

The audit runs against your theme’s actual palette every build. The shipped default palette is already AA-clean, so a stock site stays quiet; a custom theme.scss that dips below the ratio gets a warning.

Writing accessible content

The theme handles the chrome; a few habits keep your pages accessible too:

• Describe images — always give Markdown images alt text: ![A labelled architecture diagram](/img.png). Use empty alt (![]) only for purely decorative images.
• Keep headings in order — one # per page, then ##, then ###; don’t skip levels for size. The on-this-page list and screen-reader outline are built from them.
• Write meaningful link text — “read the deployment guide”, not “click here”.
• Don’t rely on color alone — pair it with text or an icon when it carries meaning.
• Label custom widgets — any interactive snippet you add should be keyboard-operable and carry an accessible name (an aria-label or visible text) and a visible focus style.

Roadmap

• Live assistive-technology smoke tests (NVDA / VoiceOver) as part of releases.
• An automated axe/pa11y pass over the built sample site.