# Accessibility

What docsp enforces at build time, what its test suite checks, and what stays your responsibility.

## Enforced by every build

These checks run in `docsp check` and `docsp build` on your site, and fail it:

- **Theme contrast.** Every pair of text and project color reaches 4.5:1 in light and dark mode: text on the accent,
  accent text on surfaces and active rows, and the header variants. See [Theming](../configuration/theming.md).
- **Page titles.** Every page needs a `title`, which becomes its h1 and its document title.

## Built into the components

- Every token color of every code theme is adjusted at build time to at least 4.5:1 on its background. See
  [Code themes](../configuration/code-themes.md).
- A "Skip to content" link at the top of every page.
- Landmarks and labels for the top bar, breadcrumb, sidebar, pagination and footer.
- Menus, tabs and dialogs with ARIA roles and keyboard support: arrow keys, Home, End and Escape in menus, arrow keys
  between code tabs, :kbd[Ctrl] + :kbd[K] for search.
- Tables and code blocks can be focused with the keyboard, so their content scrolls without a mouse.
- The active tab and sidebar entry carry `aria-current`, not only a color.
- On a locale without an interface dictionary, English interface text carries `lang="en"`.
- Figures take an `alt` text; a `dark` variant shares it.
- Version links work without JavaScript.
- The color mode is applied before first paint, so there is no flash of the wrong mode.

## Checked by the docsp test suite

The end-to-end tests of the docsp repository run on the example site, at 1440 and 390 px wide, in light and dark
mode:

- axe finds no violations on the real pages, on the component catalog, in open menus and dialogs, and with every code
  theme;
- no page scrolls sideways at 390 px;
- buttons, tabs and links in the top bar, sidebar and menus are at least 44 by 44 px at 390 px;
- pages make no request to another origin.

These tests cover the components with the example content. They do not run on your site.

## Your part

- Write `alt` text for figures and images.
- Keep heading levels in order: `##` then `###`.
- Name links by their target ("See the retry settings"), not "click here".
- If you change colors in `theme.css`, check their contrast yourself: the build does not.
- Run axe on your own built site in CI when you add custom styles or unusual content. See
  [CI checks](./ci-checks.md).
