Guide to Accessibility for Frontend Engineers

Guide to Accessibility for Frontend Engineers

Posted 2023-10-15

Web accessibility is a fundamental and essential part of building web applications. It is also often overlooked, and I've come across really great softare engineers who lack even a basic understanding of what web accessibility means.

And I understand why - most engineers I work with are young, have no visible disabilities, can see well enough to read text at 12px in font size. So accessibility needs don't really apply to them, and so I get why they don't consider accessibility needs.

But I think that this needs to change. And part of the reason I decided to start this website is to build awareness and understanding of why accessibility is so important.

What is web accessibility?

Web accessibility is the idea that a website (or web application) should be able to be used by everyone - even if they have some disadvantage (such as a disability).

Classic example is to talk about blind users (or users who cannot see very well). Can you read the next line?

Can you read this?

It is paragraph with a light yellow background, and white text. The colour contrast is poor. But this (slightly exaggerated) example is often seen on websites.

This is another example - if you can see text and associate green with success, you can probably work out that this is a success message:

<div>Status: <span class="w-2 h-2 bg-green-500 rounded inline-block"></span></div>

But for screen readers (which read out text content for blind users), or anyone who can't figure out that green == success all they see is:


The purpose of web accessibility is to not exclude people from using/reading your website

And I'd say two really good things about accessibility (especially when trying to pursade a company to take it seriously)

  • 90% of accessibility good practices are very easy to implement. (The other 10% are more time consuming). Like, 1 line changes or a new attribute to a HTML tag in a few places
  • If you make your entire website usable with just a keyboard (no mouse), you are probably 80% of the way.
  • And it benefits people who wouldn't think they would benefit from a more accessible site. (examples are below)

Why accessibility is important

We should build apps and websites that are inclusive. This means anyone can use your application... and become a customer.

If you have an inaccessible web app how do you expect people with accessibility requirements to use your site & sign up/pay?

And of course there are legal considerations which require businesses to make their websites accessible.

But even if you didn't want to focus on people with disabilities, if you make your website accessible it generally means it is better designed, more future proof and better UX for everyone.

Who should be thinking about accessibility?

This article (and site in general) is targetted towards software engineers. And it is often the software engineers who are left to make an application accessible. However it is definitely something that involves multiple types of roles:

  • designers (and UX/UI team) - crucial for creating designs which are accessible - such as colours, icons, font sizes and more
  • content writers - part of an accessible website is to have clear and simple language
  • legal - should have an understanding of legal requirements
  • testers (QA) - need to know what and how to test when it comes to accessibility
  • (and of course the engineers who have to make sure that new components/features are accessible)

How to test for accessibility

Automated tests are good for catching basic accessibility issues.

They miss a lot of bigger issues, and can sometimes raise false accessibility violations. However, I still think its worth having some CI checks to check for these basic issues.

But generally you will get best results by doing manual tests for accessibility.

Common accessibility issues

Low colour contrast

For text to be readable (and accessible), it must have good colour contrast.

Example of low colour contrast (white text on light yellow background)

Example of good colour contrast (white text on black background)

Incorrect/missing alt text for images

Screen readers (which audibly reads out content of a page) will use the alt tag in a <img> tag to describe the content.

However they are very often used incorrectly.

A good and simple rule to follow is:

  • If you were describing the page on the phone to a friend, would you even bother to mention this image?
    • e.g. for some images which are only for decorative purposes, you might not mention them on the phone
  • If not - set an empty alt tag (<img src="decorative-image.jpg" alt="" />)
  • If you would describe them on the phone - use that as the alt tag.

There are more guidelines about alt tags, but this is a good simple rule to follow.

Keyboard only usage

Ensure your site can be used with just a keyboard. Try to navigate, using mostly tab and enter key.

More complex widgets like a custom dropdown or tabs should also be able to be used with a keyboard. (see section on ARIA attributes)

This also means that anything with an onClick should be 'focusable' (with tabindex="0").

Another simple tip is if you have an onClick event handler on an element, it should be <button> element in most cases. (not a <div> or <span>). With a <button> you get much better keyboard support built in.

Use correct semantic HTML

Using correct HTML means that screen readers will understand the structure of your page much better.

✅ copied
<div class="hero-text">Bad example - should be a h1</div> <h1 class="hero-text">Good example - Using correct tag</h1> <div> Your email (inaccessible): <input name="email" /> </div> <label> Your email (accessible): <input name="email" /> </label>

Make it responsive and useable on different screen sizes

Don't forget to make sure that the site is usable on different screen sizes.

Don't assume that small window sizes means a mobile user either. Sometimes people will use a large monitor, and zoom in text (so your browser is effectively something like 400px wide) so that they can read the text.

WCAG Guidelines

The Web Content Accessibility Guidelines (commonly referred to as WCAG) are a set of recommendations (guidelines) for making your web applications accessible. If you follow all of their guidelines, then you probably have a very accessible site usable by all.

They are written up by the World Wide Web Consortium (W3C), who also define a lot of web standards (such as CSS, HTML etc).

A lot of laws throughout the world are based on the WCAG guidelines.


The WCAG guidelines are based on four principles - commonly referred to as POUR

  • Perceivable - content (e.g. text) should be able to be percieved. E.g. good colour contrast on text/backgrounds, or images should have alt-text
  • Operable - interactive elements should be usable by any input decide/type. So this means making things 'clickable' with a mouse, touch pad, keyboard, or other assistive device.
  • Understandable - people should be able to easily understand the content/meaning on the site. This means the content itself should be clear, but also things such as error messages should be clear
  • Robust - the content should be able to be used by different user agents - 'regular' browsers and assistic technology.

WCAG Guideline levels

There are three guideline levels:

  • A is the easiest to achieve. This should be the absolute minimum websites aim for
  • AA is the middle ground - most businesses should be aiming for this in my opinion
  • AAA is the most accessible, but it is the hardest to achieve, especially for highly interactive websites

ARIA attributes & role attribute

Now I've gone over WCAG, i can mention something else WC3 introduced - Accessible Rich Internet Applications specs.

They are HTML element attributes that you can add to your HTML to make your content accessible when using assistive technology.

This is a simple example of an inaccessible custom checkbox:

✅ copied
<!-- assume the .inaccessible-checkbox / .checked classes render a nice looking custom checkbox --> <div> <div id="agree-1">Agree to terms</div> <div class="inaccessible-checkbox"></div> </div> <div> <div id="agree-2">Agree to terms</div> <div class="inaccessible-checkbox checked"></div> </div>

A screen reader would not know how to interpret those <div> elements. As far as it knows, it is just an empty div with some styling.

But using ARIA properties (and role) we can tell screen readers that those divs represent a checkbox (which it understands).inaccessible

✅ copied
<span role="checkbox" aria-checked="false" tabindex="0" aria-labelledby="agree-1"></span> <label id="agree-1">Agree to terms</label> <span role="checkbox" aria-checked="true" tabindex="0" aria-labelledby="agree-2"></span> <label id="agree-2">Agree to terms</label>

Common ARIA attributes

Aria attributes have the aria- prefix. Some common ones include:

  • aria-labelledby="some-id" will tell the user agent that this element's label is #some-id
  • aria-hidden="true" will tell user agent to hide its contents to accessibility tools (e.g. screen readers).
  • For example if you had a couple of images (with alt tag) to help label something, you might want to hide one of them to screen readers as it wouldn't need to read the same thing out twice
  • aria-checked="true" used for checkboxes to say if its checked or not

Common ARIA roles

Use the role="something" attribute to tell assistive technology what kind of element this is meant to be. There are a set of standard values you can use. Here are some examples:

  • <span role="button">
  • <span role="tab"> for a tab button
  • <div role="tabpanel"> for a tab panel (which is hidden/visible)

Example of it all in use:

✅ copied
<div class="tabs"> <div role="tablist" aria-label="Sample Tabs"> <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1" tabindex="0"> First Tab </button> <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabindex="-1"> Second Tab </button> </div> <div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1"> <p>Content for the first panel</p> </div> <div id="panel-2" role="tabpanel" tabindex="0" aria-labelledby="tab-2" hidden> <p>Content for the second panel</p> </div> </div>

This is copied from mdn which goes into detail about each of the attributes - I'd recommend giving it a read.

Subscribe to my
Full Stack Typescript Developer

If you enjoyed my content and want more Full Stack Typescript content, then enter your email below.

I send a few links every couple of weeks, that I personally found useful from around the web.

Focusing on Accessibility, Typescript, NextJS, and also
engineering soft skills posts.

Welcome to my site and blog - Code Driven Development.

This is where I dive topics relating to modern software engineering - with a focus on Typescript, React, web accessibility and Agile practices

I pick topics that I think are interesting, that I think others might find interesting, or write up guides that I wish I had read before learning a topic.