Writing accessible code

Owned by Liam Tanner
May 03, 2021
3 min read

HTML / structured content

Semantic HTML gives us lots of accessibility features for free. Browsers and assistive technology know what to do with the markup. Here is some general guidance to follow:

  • Validate the HTML.
  • Use the correct element - only use a div or span if no other element fits the purpose. Don’t pick an element for purely presentational purposes.
  • Add a skip link for keyboard users as the first thing on the page, pointing at main.
  • Add the following elements as direct children of body: <header>; <main>; <aside>; <footer>.
  • Add <nav>s (with a ul of links inside).
  • Use heading elements (<h1> to <h6>) and do not skip any levels (e.g. going from <h1> to <h3>).
  • Use <section>s to group content thematically, each with a header.
  • Use <article>s for self-contained things like a blog post or a single product, each with a header.
  • Mark tables up correctly (and don’t use them for layout purposes). They should have a <caption>, <th>s for the table headers that have scope attributes for row or column (as appropriate).
  • Add a lang attribute to content not in the main language of the document.
  • Add ARIA attributes carefully - use only semantic HTML where possible. See W3C's Using ARIA for more.
  • Check that accessible names are consistent with visible names, if they’re set separately.
  • Decorative images should have alt="" or be applied with CSS as a background-image.
  • Have a site map, search function, or link rels.

Custom elements

Take extra care with custom elements. View the accessibility tree and make sure that custom elements have the following:

  • Name (this may already be set from a label)
  • Role (see ARIA Design Pattern Examples)
  • Current value (may already be set from an input)
  • Has :focus styles
  • Has an element with aria-live, if required

Forms

Here is some guidance to follow when coding forms:

  • Every form control must have an accessible name associated with it. Pick just one of these methods:
    • A label with for="id-of-the-control" (preferred method)
    • An aria-label="The label for the form" on the form control
    • An aria-labelledby="id-of-the-text-that-works-as-a-label" on the form control
  • There should be a heading.
  • Every group of related controls should have a <fieldset> with a <legend>.
  • Every appropriate field should have an autocomplete attribute with the appropriate value. See the WCAG Input Purposes for User Interface Components list.
  • Use HTML5 input types to aid user input.

Errors

Here is some guidance on how to handle error messages in your code:

  • Where possible, have error messages as children elements of label elements.
  • Where not possible, use aria-describedby="id-of-the-error-message-element" on the form control.
  • Add aria-invalid to invalid fields using client-side scripting.
  • Add aria-required to mark required fields as well as the HTML5 required attribute.

CSS / presentation

Here are some tips for using CSS in an accessible way:

  • Only use CSS for layout and formatting, not whitespace in the HTML.
  • Make all click or touch targets at least 44 x 44 pixels (except when inline in a block of text).
  • Set a background-color whenever a color is set.
  • Use responsive web design.
  • Don’t set fixed width containers (that would clip, truncate, or obscure text, or cause horizontal scrolling, when text is enlarged).
  • Don’t use viewport-based units for font size.
  • Try to avoid flashing content (AAA). Any areas with flashing should be small (about thumbnail size), and flash fewer than three times a second (AA).

JS / behaviour

Here are some tips for using JS in an accessible way:

  • Every component should be keyboard accessible, and users should be able to tab in to and out of it (AA allows for some exceptions).
    • The tab order should also be logical. Don’t add tabindex if you can avoid it.
  • Use input-agnostic event handlers (focus, blur, click), not touch-only.
  • Only perform actions at the end of an event, not on down events. Alternatively, provide an undo option.
  • Try to avoid hiding content behind a hover. If you do, make sure:
    • The revealed content can be hovered on too
    • It can be dismissed by moving the pointer or changing focus (e.g. using Esc)
    • It stays until it’s dismissed
  • Any audio or video should have pause / stop controls, and should not autoplay.
  • Don’t use automatic redirects like meta refresh and redirect.
  • Have pause, stop, and hide controls for any moving, blinking, or scrolling content.
  • Any character key shortcuts should be able to be turned off, remapped, or are only active on focus.
  • Components should be accessible by default, by having a prop-based option for turning off the added accessibility features, in case the components are being combined in a different way.