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.
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.
Don’t
<div class="button" onclick="save()">Save</div>Do
<button type="button" onclick="save()">Save</button>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>andscope.
The guide for content designers has more about headings and lists.
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.
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.
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.
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.
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.
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 withshowModal()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>withtabindex="-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.
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.
Don’t
<button>
<svg>…</svg>
</button>Do
<button>
<svg aria-hidden="true">…</svg>
<span class="visually-hidden">Search</span>
</button>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-expandedon a button that opens and closes something.aria-pressedon a toggle button.aria-current="page"on the link to the current page.aria-invalidon a field with an error.
Never put ARIA on an element that contradicts what it is, like role="heading" on a <button>.
Hide content the right way
There are three ways to hide something, and each hides it from someone else:
- From everyone:
display: none,visibility: hiddenor thehiddenattribute. 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.
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.
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.
Don’t
<input type="email" placeholder="Email">Do
<label for="email">Email</label>
<input type="email" id="email">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.
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.
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-scaleoruser-scalable=noin the viewport meta tag. - Use
remoremfor 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.
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.
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
currentColorfor 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.
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.
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
- eslint-plugin-jsx-a11y (opens external website), accessibility rules for JSX. Vue, Svelte and Angular have similar plugins.
- Run automated checks in your pipeline, in the guide for testing
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
- Inclusive ComponentsHeydon Pickering
- Form Design PatternsAdam Silver
- Web Accessibility CookbookManuel Matuzović
- Practical Web AccessibilityAshley Firth