Skip to content
SwiftDocsv1.3.1

Accessibility

SwiftAgency scores 100 for accessibility in Lighthouse on every page tested, in all three languages. An automated score only catches part of the problem, so the rules below are built into the components rather than left to chance.

Built in

Section titled “Built in”

Structure

  • Landmarks on every page (header, nav, main, footer) and one h1, with headings in order.
  • A “Skip to content” link as the first thing the keyboard reaches.
  • <html lang> per page, and lang on any text in another language, such as English fallback content.

Keyboard and focus

  • Everything works with a keyboard. Focus is shown with a 2px accent outline, offset so it never hides text.
  • The mobile menu is a native <dialog>: focus stays inside while it’s open, and Esc closes it.
  • The preset switcher uses the native Popover API, so Esc and clicking outside close it.
  • FAQ answers and open roles use native <details>, which work with every assistive technology.

Colour

  • Every text colour in every preset passes WCAG AA (4.5:1) against the surface it sits on, in light and dark. The Presets page shows the ratios.
  • Decorative colour (ink-faint) is never used for text.
  • State is never shown by colour alone: the current page is underlined, selected chips change fill and have aria-pressed.

Forms

  • Every field has a visible label. Errors are written out, linked with aria-describedby, and set aria-invalid.
  • On submit, focus moves to the first field with a problem, and then to the success message.
  • Error messages say what to do, not just what went wrong.

Motion

  • Everything that moves respects prefers-reduced-motion. See Motion.
  • The marquee pauses on hover and focus.

Images and icons

  • Every content image requires alt text; the build fails without it. Decorative images use alt="".
  • Icons are hidden from screen readers unless given a label.

When you extend the theme

Section titled “When you extend the theme”
  • Alt text describes what matters in the image for this page, in a sentence. Not “image of”.
  • Links say where they go. “Read the Halden Rail case study”, not “Read more”. Where a design needs a short visible label, add the rest in <span class="sr-only">.
  • Use buttons for actions and links for navigation. A <div> with a click handler can’t be reached by keyboard.
  • Keep text roles. New components take text colours from ink and ink-muted, never ink-faint.
  • Check new colours. If you make a preset, test every text pair at 4.5:1.
  • Test with the keyboard. Tab through a new page once before shipping: you should always see where you are.

SwiftAgency is made byLessCodexLicence