Skip to content
docsp
On this page

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.
  • 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.
  • 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, Ctrl + 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.
↑ ↓ to move↵ to openSearching docsp