Site accessibility

Current support

VoiceOver / TalkBack / NVDA

All landmarks (header, nav, main, aside) have accessible names through aria-label or aria-labelledby. Aside headings are visually hidden to preserve the article hierarchy while remaining available in the rotor. Decorative CSS prefixes (“# ”, “./”, “$ ”) use empty alternative text to stay out of the accessibility output.

Keyboard and focus

A skip link targets #main. Focus uses a visible :focus-visible outline (2px yellow). Interactive elements support Tab/Shift+Tab. Long code blocks support keyboard scrolling through tabindex="0" and role="region".

Light / Dark / High Contrast

CSS custom properties control the palette. Light and dark themes follow prefers-color-scheme; prefers-contrast: more provides a black-and-white palette with strong accents.

Reduce Motion

Transitions and animations are reduced to 0.001ms with prefers-reduced-motion: reduce or the body.no-motion class.

Target size

Navigation buttons use a minimum 44×44 target, following Apple HIG and WCAG 2.2 AAA target-size guidance.

English content and language metadata

Pages declare <html lang="en">. Code and inline fragments are also marked lang="en" by the rendering pipeline so VoiceOver can choose the appropriate pronunciation.

How we test

1. Manually test four representative pages (home, smells index, a pattern, and a chapter) with VoiceOver and a keyboard.
2. Check color-token contrast separately for dark, light, and prefers-contrast: more. The target is WCAG 2.2 AA for normal text and AAA for large text.
3. Run Lighthouse accessibility and axe-core checks in CI after each build, with the JSON report at /a11y-report/latest.json (see below).
4. Treat content and template edits as part of the accessibility surface and apply the same checklist.

Latest self-audit

Automated CI auditing has not been run yet. Until then, this page uses a manual snapshot from 2026-05-17: four representative pages were reviewed (home, /smells/, /patterns/icon-button-label/, and /chapters/05-...). The recorded P1 issues (contrast for --marker and decorative CSS prefixes exposed to assistive technology) and P2 issues (target size, lang="en" on code, visible active states, and heading hierarchy) were closed. The full report is stored in the repository: outputs/a11y-audit.md.

Known limitations

These items remain on the improvement list.

• nice-to-have Skip link targets #main only P3.2

  Article pages could also offer skip links to the sidebar and related panel. Currently, the skip link targets #main only.

• nice-to-have No UI toggle for body.no-motion P3.5

  The class works, but there is no interface toggle. The system prefers-reduced-motion preference is supported.

• editorial Curated catalog summaries lag behind the actual links EDIT-1

  npm run check:curated reports differences in catalog/{smells,patterns}/index.md. The obsolete slugs silent-error-in-media, product-trust-risk, and app-store-label-risk need correction. The site derives relationships from the cards; the curated Markdown tables still need an editorial update.

Design exceptions

Terminal style and monospaced type

The book uses SFMono / Cascadia Code / Menlo as part of its visual identity, with a 1.74 line height and responsive clamp() sizes. Decorative CSS prefixes are hidden from assistive technology to keep the terminal style from adding screen-reader noise. These choices still need to meet WCAG readability and contrast requirements.

Color as a visual taxonomy

Tags combine a colored border with a text label: “smell”, “pattern”, or “chapter”. Color is not the only signal, following WCAG 1.4.1.

How to report a problem

If a problem blocks your task with VoiceOver, a keyboard, contrast settings, or Dynamic Type, open an issue in the book repository or contact us. Include:

1. The page URL.
2. The task you were trying to complete.
3. The assistive technology or system setting you use.
4. What happened and what you expected.

We recommend the same accessibility bug-report template for iOS teams. See catalog/README.md and Chapter 13.