Skip to main content
Accessibility
for teams

Accessibility for frontend developers

full guide

You turn designs into code that browsers, keyboards and screen readers have to understand. Most of that work is done by choosing the right HTML element. This guide helps you build accessible interfaces and keep them accessible. It is a starting point.

New to accessibility? Where to start as a team

How to build accessible interfaces

chapter 1

Semantic HTML

Must know: Use the element that does the job

A <button> can get keyboard focus, works with Enter and Space, and a screen reader announces it as a button. A <div> with a click handler does none of that. You can add it all back with tabindex, role and keyboard events, but you will probably forget something.

  • Use <button> for actions.
  • Use <a href> for going to another page or place.
  • Use <input>, <select> and <textarea> for data, and <details> for content that opens and closes.

Style the native element to look the way the design asks. That is almost always less work than rebuilding its behaviour.

A button that saves a form.

Don’t

<div class="button" onclick="save()">Save</div>

Do

<button type="button" onclick="save()">Save</button>
WCAG 2.1.1 KeyboardWCAG 4.1.2 Name, Role, Value

Give the page a structure

Screen reader users jump through a page by landmarks, headings and lists, the way sighted users scan it. That only works if the structure is in the HTML, not just in the styling.

  • Use <header>, <nav>, <main> and <footer> for the main parts of the page.
  • Use one <h1> and headings that don’t skip a level. Choose the level by its place in the structure, and the size with CSS.
  • Mark up lists as <ul> or <ol>, and data tables with <th> and scope.

The guide for content designers has more about headings and lists.

WCAG 1.3.1 Info and Relationships

Set the language and the page title

Add a lang attribute to the <html> element, like lang="en". A screen reader uses it to choose the right voice and pronunciation. Add lang to quotes and phrases in another language too.

Give every page a unique <title> that starts with what is on the page. It is the first thing a screen reader announces. In a single-page app, update the title after every route change.

WCAG 2.4.2 Page TitledWCAG 3.1.1 Language of PageWCAG 3.1.2 Language of Parts

Give every image the right alt attribute

Every <img> needs an alt attribute. Without one, some screen readers read out the file name.

  • Informative image: describe what it shows or means.
  • Decorative image: use an empty alt="", so screen readers skip it.
  • Icon in a button or link: hide the icon with aria-hidden="true" and give the button or link the name.

Make it possible to edit alt text in your CMS. What the text should say is explained in the guide for content designers.

WCAG 1.1.1 Non-text Content

Keyboard and focus

Must know: Never remove the focus outline

Keyboard users need to see where they are. The browser shows a focus outline by default. Removing it makes your site unusable for them.

Does the outline bother mouse users? Style :focus-visible instead of :focus. The browser then shows the focus style for keyboard use and not after a mouse click.

Make sure a sticky header, a cookie banner or a chat button doesn’t cover the element that has focus. scroll-padding-top helps for sticky headers.

Watch out

Never write outline none on an interactive element, unless you replace it with a focus style that is at least as visible.

WCAG 2.4.7 Focus VisibleWCAG 2.4.11 Focus Not Obscured (Minimum)

Keep the code order and the visual order the same

Keyboard focus and screen readers follow the order of the HTML, not the order on the screen. CSS like order, flex-direction: row-reverse or grid placement can change what people see without changing where the focus goes.

Put elements in the HTML in the order people read and use them, and use CSS for the layout.

Don’t use a positive tabindex, like tabindex="1". It takes elements out of the normal order and is almost impossible to keep right. tabindex="0" and tabindex="-1" are fine where you need them.

WCAG 1.3.2 Meaningful SequenceWCAG 2.4.3 Focus Order

Add a skip link

Make the first focusable element on the page a link to the main content, like <a href="#main">Skip to main content</a>. Keyboard users can then skip the navigation on every page.

The link can be hidden until it gets focus, but then it must become visible. Hide it with a visually-hidden class, not with display: none, or it can’t get focus at all.

The skip link is the first thing on the page. It appears when it receives keyboard focus, and takes people past the menu to the main content.
WCAG 2.4.1 Bypass Blocks

Move focus when the content changes

When something opens, the focus has to go with it. Otherwise keyboard and screen reader users stay behind, somewhere the content no longer is.

  • Dialogs: move focus into the dialog when it opens, and back to the button that opened it when it closes. A <dialog> opened with showModal() does most of this for you, and makes the rest of the page inert.
  • Route changes in a single-page app: move focus to the new content, for example its <h1> with tabindex="-1", and update the page title.
  • Removed content: when someone deletes an item, move focus to a logical place nearby, not back to the top of the page.
WCAG 2.4.3 Focus Order

Names, roles and states

Must know: Give every control an accessible name

A screen reader announces the name of every button, link and form field. Without a name, a button is just “button”.

Most elements get their name from their text or their <label>. Icon buttons don’t have one, so add text that is visually hidden, or an aria-label. Visually hidden text has an advantage: browser translation tools translate it too.

If a control has visible text, the accessible name must contain that text, preferably at the start. Speech recognition users say what they see, like “click Send”. That doesn’t work if the name is “Submit form”.

You can check the name in the accessibility panel of your browser’s developer tools.

A search button with only an icon.

Don’t

<button>
  <svg>…</svg>
</button>

Do

<button>
  <svg aria-hidden="true">…</svg>
  <span class="visually-hidden">Search</span>
</button>
WCAG 4.1.2 Name, Role, ValueWCAG 2.5.3 Label in Name

Must know: Use ARIA only when HTML can’t do it

No ARIA is better than bad ARIA.

ARIA changes what a screen reader announces. It doesn’t change what an element does. role="button" on a <div> is a promise that the element works like a button: you still have to add focus and keyboard support yourself.

So use a native element when one exists. Use ARIA for what HTML can’t express, and keep it up to date:

  • aria-expanded on a button that opens and closes something.
  • aria-pressed on a toggle button.
  • aria-current="page" on the link to the current page.
  • aria-invalid on a field with an error.

Never put ARIA on an element that contradicts what it is, like role="heading" on a <button>.

WCAG 4.1.2 Name, Role, Value

Hide content the right way

There are three ways to hide something, and each hides it from someone else:

  • From everyone: display: none, visibility: hidden or the hidden attribute. Use it for content that isn’t relevant now, like a closed menu.
  • From the screen only: a visually-hidden class. Screen readers still read it. Use it for extra context, like the name of an icon button.
  • From assistive technology only: aria-hidden="true". Use it for decoration that is already said in text, like an icon next to a word.
Watch out

Never put aria-hidden on an element that can get focus, or on an element that contains one. Keyboard users can then reach something a screen reader stays silent about.

WCAG 1.3.1 Info and Relationships

Announce status messages

Some changes are important, but not important enough to move focus to: “Added to your basket”, “12 results”, “Saved”. A screen reader user doesn’t notice them unless you put them in a live region.

Add an element with role="status" to the page when it loads, and change its text when something happens. A live region that is added at the same moment as its text is often not announced.

Use role="alert" only for urgent messages. It interrupts whatever the screen reader is saying.

WCAG 4.1.3 Status Messages

Forms

Connect every field to a label

A <label> with a for attribute gives the field its name and makes the label clickable, so the target gets bigger. A placeholder is not a label: it disappears as soon as someone types, and its contrast is often too low.

Group radio buttons and checkboxes that belong together in a <fieldset> with a <legend>. A screen reader then reads the question with each option.

The guide for UX and UI designers explains how to design accessible forms.

A field for an email address.

Don’t

<input type="email" placeholder="Email">

Do

<label for="email">Email</label>
<input type="email" id="email">
WCAG 1.3.1 Info and RelationshipsWCAG 3.3.2 Labels or Instructions

Help the browser fill in the form

Typing is hard work for many people. Add an autocomplete attribute to fields about the user, like autocomplete="email", "given-name" or "street-address". The browser can then fill them in.

Use the right type and inputmode as well, so phones show a keyboard that fits: type="email", type="tel", or inputmode="numeric" for a code.

WCAG 1.3.5 Identify Input Purpose

Make error messages reach everyone

An error message that only appears in red, somewhere on the screen, is missed by many people.

  • Show the message as text next to the field, and connect it with aria-describedby.
  • Set aria-invalid="true" on the field.
  • After submitting, show a list of errors at the top with links to the fields, and move focus to it. Or move focus to the first field with an error.

Test your own validation with a screen reader. Native browser validation is a reasonable start, but its messages are hard to style and to understand.

WCAG 3.3.1 Error IdentificationWCAG 3.3.3 Error Suggestion

CSS and layout

Build layouts that reflow and zoom

People with low vision zoom in, often to 200% or 400%. At 400% a 1280 pixel wide screen is only 320 CSS pixels wide.

  • Never stop people from zooming: no maximum-scale or user-scalable=no in the viewport meta tag.
  • Use rem or em for text, so it follows the font size people set in their browser.
  • Make sure the page works at 320 CSS pixels wide without scrolling in two directions. Tables, maps and code blocks may scroll sideways.

The guide for UX and UI designers explains how to design for zoom.

WCAG 1.4.4 Resize TextWCAG 1.4.10 Reflow

Don’t fix the height of text

Some people change the line height, letter spacing and word spacing to read more easily. Text then takes up more space. A fixed height with overflow: hidden cuts it off.

Let elements with text grow with their content. Use min-height if a block needs a minimum size, and test with the text spacing bookmarklet from the guide for testing.

The same button with default spacing and with the text spacing WCAG tests. Because the button has no fixed height or width, it grows and the text stays readable.
WCAG 1.4.12 Text Spacing

Respect the user’s settings

People set their computer to work for them. Your CSS can follow those settings.

  • Reduced motion: movement can make people dizzy or sick. Turn off parallax, large transitions and animations that start by themselves inside @media (prefers-reduced-motion: reduce).
  • Forced colours: Windows contrast themes replace your colours. Backgrounds and box shadows disappear. Use real borders and outlines, and currentColor for icons, so buttons, fields and focus stay visible. Test in forced colours mode with the rendering tools of your browser.
  • Dark mode: if you support it, check the contrast of both themes.

Make targets big enough

Small targets are hard to hit with a tremor, on a moving train or with a big thumb. Make buttons and links at least 24 by 24 CSS pixels, or leave enough space around them. 44 by 44 pixels is better.

Put the padding on the link or button itself, not on the icon inside it. Then the whole area responds to a click or tap.

A 16 px icon inside a 44 × 44 px target
WCAG 2.5.8 Target Size (Minimum)

Components and frameworks

Check a component library before you trust it

A popular component library is not automatically accessible. Before you choose one, test the components you need with a keyboard and a screen reader: a dialog, a menu, a date picker, tabs.

Build accessibility into your own components, once. Every page that uses them gets better at the same time, and every fix only has to be made in one place.

Frameworks don’t make a page inaccessible, but they make it easy to forget the basics. A click handler on a <div> looks just as clean in a component as a <button> does.

Treat ARIA patterns as a starting point

The ARIA Authoring Practices Guide shows how tabs, comboboxes and menus should work with a keyboard. It is useful, but its examples are not production code, and not every pattern works well with every screen reader.

Choose the simplest pattern that does the job. A list of links often works better than an ARIA menu, and a disclosure with <details> often works better than an accordion widget.

WCAG 4.1.2 Name, Role, Value

Making accessibility part of your work

chapter 2

Accessibility is cheapest to fix in the code you are writing today. Check your own work before you open a pull request. Tab through it, zoom in and listen to it with a screen reader.

Build to WCAG 2.2 level AA. That is what most laws and the European standard EN 301 549 come down to. The guide for product managers explains which law refers to which version.

In your workflow

Test while you build

Before you open a pull request, take five minutes:

  • Put your mouse away and use your work with only a keyboard.
  • Zoom in to 400%.
  • Listen to it with a screen reader: VoiceOver on a Mac, NVDA on Windows.
  • Check names, roles and states in the accessibility panel of your browser’s developer tools.

The guide for testing explains each of these checks.

Let tools catch the easy mistakes

Automated checks find the mistakes a computer can see: a missing label, a missing alt attribute, an invalid ARIA attribute. Let them run where you already work:

  • A linter in your editor, so you see the issue while you type.
  • axe-core in your component tests and end-to-end tests, so a new issue fails the build.

Tools find only part of the issues. A clean report doesn’t mean your work is accessible.

Useful links

Include accessibility in code review

Add a few fixed questions to every code review:

  • Does it work with only a keyboard, and is the focus visible?
  • Does every control have a name, and do states like expanded or selected change in the code?
  • Is the HTML semantic, and does the ARIA match it?

Agree with your team that a pull request with known accessibility issues is not done.

Learning more

Must know: Take a course that goes deeper

This guide is a starting point. If you want to really understand how accessibility works in the browser, take Practical Accessibility by Sara Soueidan. It is the best accessibility course for developers I know.

It explains the accessibility tree, semantic HTML, responsible use of ARIA, accessible names, forms, live regions, keyboard navigation and forced colours mode, and how to test with a screen reader. You can watch the captioned videos or read every chapter as text, at your own pace.

Books about accessible frontend development

reading list