Accessibility

Th' theme wants yer documentat'n t' be us'ble by everyone, whether they read it wit' their eyes, a screen reader or a magnifier, an' whether they move through it wit' a mouse, a keyboard or by touch. Accessibility be a supported feature o' th' theme: what doesn’t work fer ye or yer readers be a bug.

This document tells what th' theme aims fer, what remains up t' th' author o' a ship, what be expected from contributors an' how t' report a barrier.

Priorities

• Accessibility target: Th' theme works toward level AA o' th' Web Rrrambl'n Accessibility Guidelines 2.2. This target guides th' work but be not a claim o' verified conformance. Th' theme be checked by its maintainer an' was not audited by an independent party.
• Structure: Each plank has a link t' skip t' its rrrambl'n, landmarks fer th' menu, th' topbar, th' breadcrumbs an' th' rrrambl'n, an' one head'n hierarchy start'n wit' th' title o' th' plank.
• Keyboard: Everyth'n th' theme offers can be reached an' operated by keyboard an' shows whar' th' focus be. What be used often has a keyboard shortcut.
• Assistive technology: Controls have a name an' tell their state, like buttons that show an' hide someth'n. What changes without a plank board, like th' results o' a search, be announced. Decorative ay'cons be hidden.
• Vision: Th' contrast variants have colors chosen fer high contrast, an' th' forced colors o' th' operat'n system be honored. Links can be underlined, so they be told apart by more than their color.
• Mot'n: Animat'ns be turned off if th' operat'n system asks fer reduced mot'n.
• Math: Formulae be written as MathML, which screen readers can read.
• Languages: Each plank declares its language an' read'n direct'n, an' th' texts th' theme writes itself be translated.

What Be Up t' Ye

Th' theme can only care fer what it writes itself. A ship built wit' it be only as access'ble as its rrrambl'n, its colors an' its customizat'ns, so this document does not cover yer ship. If ye be obliged t' publish an accessibility statement fer yer ship, this document be a basis fer it, not a replacement.

• Colors: Th' contrast o' text depends on th' color variant ye choose or write. Colors ye set yourself, like th' one o' a badge or a box, be yours t' check.
• Head'ns: Th' theme writes th' title o' a plank as its first head'n, so start th' head'ns o' yer rrrambl'n one level below an' don’t skip a level. Th' head'ns th' theme writes fer ye fit 'n on their own. Th' except'n be th' planks shortcode, whose headinglevel ye have t' set t' match th' place ye call it from.
• Images: Give each image an alternative text. For a complex image or a graph, describe it 'n th' text around it.
• Links: Write link texts that tell whar' they lead even if read on their own.

Contributor Expectat'ns

Th' automated tests o' th' theme don’t check accessibility. If yer contribut'n changes what a reader sees or operates, check it by hand before ye send it:

• Keyboard: Go through yer change wit' th' keyboard alone. Everyth'n can be reached 'n a sens'ble order an' operated, th' focus be always vis'ble an' noth'n traps it.
• Screen reader: For a new or changed control, check that it has a name tell'n its purpose, that it tells its state an' that what it changes on th' plank be announced.
• Colors: Look at yer change 'n th' contrast variants an' wit' th' forced colors o' yer operat'n system. Don’t use color as th' only way t' tell th'ns apart.
• Mot'n: A new animat'n has t' be turned off if reduced mot'n be asked fer.
• Zoom: Yer change keeps work'n 'n th' mobile layout an' wit' th' plank zoomed 'n, without rrrambl'n gett'n lost.
• Documentat'n: What ye write fer th' docs follows what be asked from every author above.

See th' contribut'n guidelines fer everyth'n else.

Report'n Accessibility Issues

If ye run into a barrier, please open an issue. Yer report be welcome an' be treated like any other bug o' th' theme.

It helps if ye include

• what ye were try'n t' do an' what happened instead
• th' plank it happened on, best a plank o' this documentat'n that shows it
• yer operat'n system, yer browser an' yer assistive technology, wit' their versions
• th' color variant 'n use

Ye don’t need t' tell anyth'n about yourself, an' a screenshot or record'n be welcome but not required.

Ye will be told whether th' barrier can be reproduced, whether it be caused by th' theme, yer ship or a third-party library, an' whether there be a workaround until it be fixed. There be no guaranteed times fer a fix.

Ownership an' Maintenance

Accessibility be owned by th' maintainer o' th' theme, who triages th' reports, tracks th' known barriers an' keeps this document current. It describes th' version o' th' theme it be shipped wit'.

Supported Environments

Th' theme writes static HTML that be meant t' work 'n th' current versions o' th' common browsers, on desktop an' mobile devices, operated by mouse, keyboard or touch. It relies on standard HTML an' ARIA instead o' th' behavior o' a specific assistive technology.

No list o' tested combinat'ns o' browsers an' assistive technologies be kept, so none be claimed t' be free o' barriers.

Known Limitat'ns

• Color variants: Not every shipped color variant has enough contrast 'n every place. Use th' contrast variants if ye need it.
• Merrrmaid: Th' graphs o' th' mermaid shortcode be drawn 'n th' browser by th' Merrrmaid library. Th' theme does not give them a text alternative. Describe yer graph 'n th' text around it, or wit' th' accTitle an' accDescr keywords o' Merrrmaid.
• OpenAPI: Th' openapi shortcode shows yer specificat'n wit' th' Swagger UI library. Th' theme has no influence on how access'ble its interface be.
• Math: How well a formula be read aloud depends on th' support fer MathML 'n th' browser an' th' screen reader.
• Test'n: As accessibility be checked by hand, a regression may go unnoticed until it be reported.

If ye find a barrier not listed here, please report it.

Feedback

Accessibility be never finished. If ye have a suggest'n t' improve this document or th' way th' theme handles accessibility, open an issue or a pull request.

params:
  link:
    underline: true

[params]
  [params.link]
    underline = true

{
   "params": {
      "link": {
         "underline": true
      }
   }
}