Autopsy of an inaccessible website: 5 code errors that fail an audit

A website doesn’t usually fail an accessibility audit because of how it looks, but because of how it’s written. The same things almost always fail: elements that look like controls but aren’t, misplaced ARIA, fields with no name and focus that gets lost. These are the five errors we find most often, and how to write them properly.

Why a website fails technically

A screen reader doesn’t see the page. It reads what the browser tells it about the page: what each thing is, what it’s called and what state it’s in. That information comes from the HTML. If the code says “box” where it should say “button”, the person using it gets a box.

UNE-EN 301549 refers to WCAG 2.1 level AA for the web. The five errors in this article fail criteria at that level.

• What we find

  • A <div> with a click event
  • A modal window that lets the focus escape
  • aria-hidden on a link
  • A field with only a placeholder
  • White text over a photo

• What we write

  • <button type="button">
  • <dialog> opened with showModal()
  • The link, visible to everyone or to no one
  • A visible <label for>
  • The text on a solid background

The five errors

1. A div acting as a button

What we find: a <div> or a <span> with a click event. It works with a mouse. With a keyboard you can’t reach it, and the screen reader doesn’t say it’s a button.

It fails criteria 2.1.1 (Keyboard) and 4.1.2 (Name, Role, Value).

How to write it: <button type="button">. You can reach it with Tab and activate it with Enter and the space bar, and the screen reader announces it as a button. All of that comes built in, without one more line of JavaScript.

2. A modal window that lets the focus escape

What we find: a window opens and the focus stays on the page behind it. With Tab, the person keeps moving through links they can’t see. When the window closes, the focus doesn’t go back anywhere.

It fails criterion 2.4.3 (Focus Order). The opposite, a window you can’t leave with a keyboard, is a keyboard trap and fails 2.1.2.

How to write it: with <dialog> and showModal(). The browser moves the focus into the window, makes the rest of the page inert and closes it with Escape. Always check that, when it closes, the focus goes back to the button that opened it.

3. ARIA that’s unnecessary or gets in the way

What we find: role="navigation" on a <nav>, which repeats what the element already says. It doesn’t break anything, but it’s noise. The serious problem is something else: aria-hidden="true" on a link or a button. The keyboard reaches it and the screen reader doesn’t announce it.

It fails criterion 4.1.2 (Name, Role, Value).

How to write it: with the first rule of ARIA. If there’s an HTML element that already does what you need, use that element. And anything hidden from the screen reader is hidden from the keyboard too.

4. Fields with no label

What we find: a field with the help text inside it, in the placeholder, and no label. When you start typing, the text disappears. It often has low contrast and not all screen readers announce it as the name.

It fails criteria 1.3.1 (Info and Relationships) and 3.3.2 (Labels or Instructions).

How to write it: every field with its own visible <label for="…">, above the field, and the placeholder only for an example, if one is needed.

5. Text over an image with no contrast

What we find: a white headline over a photo. On one part of the photo you can read it and on another you can’t. On mobile, with a different crop, it’s harder to read.

It fails criterion 1.4.3 (Contrast (Minimum)): 4.5:1 for normal text and 3:1 for large text.

How to write it: the text on a solid background or a scrim that keeps the contrast at the worst point of the image, on every screen size. Or the text outside the image.

How we avoid this on our websites

We talk about it in the design, before writing any code: what each control is, how you reach it with a keyboard and what contrast it has. Then every change goes through automated checks for contrast, reflow and navigation before it’s published. And what a machine can’t see, we review with a keyboard and a screen reader.

If your team builds the website and wants to know where it stands, the audit is the first step.