Accessibility (a11y)

!Note: this page is auto-generated from docs/accessibility.md.

Head Start aims to provide an accessible baseline, by providing helper classes and components.

CSS helper classes

Head Start provides CSS helper classes for improved accessibility:

---
import '@assets/a11y.css';
---

<span class="a11y-sr-only">
  This element is visually hidden, while its content is still 
  accessible by assistive technology like screen readers (sr).
</span>

<a href="..." class="a11y-kb-only">
  This element is visually hidden, and appears 
  only when element has keyboard (kb) focus.
</a>

Skip Link component

Head Start provides a Skip Link component that enables keyboard users and users of assistive technology to jump over parts of the UI that are repeated. It's pre-configured in the Default template.

A11y testing

• Basic a11y validation is provided as part of npm run lint:html, which includes validate a11y. This script also runs on pull requests.

• Test manually using only your keyboard and a screen reader like VoiceOver.

• Test regularly with tools like Google Lighthouse and WebAIM WAVE.

• When adding automated tests, consider Cypress Axe or Playwright Axe.

Best practices

Head Start aims to stay close to the web standards. Here's a few tips to help keep it accessible:

• Use semantic HTML as a baseline.

• Use media queries for a11y like prefers-reduced-motion and prefers-contrast.

• Use native elements for interaction like <form>s, <label>led <input>s, <output>s, <dialog>, <details> with <summary> and native API's like the Popover API.

• Add relevant ARIA roles and attributes on custom interactive components.

• Require alt texts on assets in the CMS and use their value in templates.