lukegarrigan

Fixing accessibility issues using Axe

The last couple weeks I’ve had to hone in on some accessibility requirements for my job. I’m currently writing an application that’ll hopefully be used by millions of people in the UK so it’s fundamental we make it accessible.

Accessibility — and I’m guilty of this — is often an afterthought for programmers, it’s something a lot of companies tend to ignore until they’re told by their customers that their application is unusable.

Recently I’ve been using Axe DevTools extensively and has now earned its rightful spot in my developer quiver. Axe is a lightweight browser extension which does the following:

  • Identifies accessibility violations
  • Shows you exactly where the issue is (which element)
  • Explains why it’s an issue
  • Offers potential fixes

To prove the brilliance of Axe I’ll run it on one of my websites planfree.dev (a completely free planning poker application).

It found 5 issues with this simple landing page, which is just a button and some text:

As you can tell from the screenshot, Axe places issues in categories and found 1 serious, 2 moderate and 2 minor on this simple page, crazy.

Lang attribute

The serious issue: the <html> element does not have a lang attribute. If the attribute value is the empty string (lang="") which mine is, the language is set to unknown. Unbeknownst to me, setting the language tag is required to allow assistive technologies such as screenreaders to use the correct pronunciation.

Elements must have sufficient colour contrast

A handy website to do a quick check between a background and foreground colour to validate WCAG compliance is webaim.org – chuck that in your browser favourites. The problem I’ve got with my “Start new game” button is a little bit tricky: Element’s background color could not be determined because it’s partially obscured by another element. I’ve had the same error before which took over 3 hours of attempting different CSS solutions to be compliant. Let’s hope this one’s simpler.

Here’s the culprit:

<button class="button" :class="{ disabled: clickedStart }" @click="startGame()">
    <span v-if="!clickedStart">Start new game</span>
</button>

Anything jumping out to you there? Nothing jumped out to me so I began commenting out code until the problem disappeared (or appeared). I commented out the <span> and got a different error, span must be the issue. Let’s take a look at the CSS:

span {
    line-height: 100px;
    font-family: "Montserrat", sans-serif;
    font-size: 26px;
    font-weight: semibold;
}

line-height: 100px, somebody else must have written that code 😂 Let’s try removing that:

0 axe issues

woohoo! 🥳 Who knew having such a large line-height would be so insidious?

Navigating without a mouse

One metric people tend to use when making their websites accessible is the no-mouse test. Can you use your website without picking up the mouse? Can you perform all the actions you could perform with a mouse?

A keyboard-only user could be:

  • Anyone with fine motor control restrictions (parkinson’s, severe arthritis, etc.)
  • Those with disabled hands/arms (accidents, congenital disability, etc.)
  • Anyone with large motor control issues (MS, etc.)
  • Those who prefer to use a keyboard for most navigation (software developers, typists, etc.)
  • Those that don’t have a mouse (tablets, cellphones)
https://blog.novacare.no/can-you-navigate-your-website-without-using-a-mouse/

Let’s give this a go on planfree.dev.

gif showing it's not possible to tab to a button

hmm, that’s not good. I can’t even get to “Start new game” 🤦‍♂️. I must have knocked this out with some CSS as by default you can tab HTML buttons.

.button {
  &:focus {
    outline: none;  // the culprit
  }
  // other css
}

I’m unsure what that was doing there, let’s delete it and try again:

Gif showing it's possible to tab to a button

Much better, it may look a bit dodgy but I can sort that out another time.

Planfree.dev allows players to choose an estimate for how long the next chunk of work will take using the Fibonacci system. Let’s run Axe on the game page:

14 Axe issues

14 issues! And 1 of those is critical. The critical issue is that buttons must have discernable text. Buttons must clearly describe the function, action or destination for users with assistive technology. Screen readers use this information to inform the user the purpose of the button. Can you see which button I’ve not correctly labelled? 

<button class="star-button" @click="goToGithub()"></button>

It’s the button I use to tempt people to give the repo a star on GitHub, let’s sort that out.

By default, a button’s accessible name is the content between the opening and closing <button> tags, an image’s accessible name is the content of its alt attribute, and a form input’s accessible name is the content of the associated <label> element.

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label

The issue here is that we don’t have any content between the opening and closing <button> tags. To remedy this I need to add an aria-label:

<button class="star-button" @click="goToGithub()" aria-label="Go to the GitHub repository">

Which fixes the critical error ✅

All of those buttons at the bottom had the same line-height issue as previously mentioned on the home page, simply removing the line-height: 100px sorted those too.

Page should contain a level-one heading

Every page should have a <h1> element:

Screen reader users can use keyboard shortcuts to navigate directly to the first h1, which, in principle, should allow them to jump directly to the main content of the web page. If there is no h1, or if the h1 appears somewhere other than at the start of the main content, screen reader users must listen to more of the web page to understand its structure, wasting valuable time.

https://dequeuniversity.com/rules/axe/4.3/page-has-heading-one

Because this page is the game I have no requirement for a level-one heading, it would probably look a little bit dodgy. To combat this I’m going to add an element that only screen readers will be able to see, so they can navigate to it when needs be:

<h1 class="screen-reader-only">Planfree.dev game lobby</h1>

And the CSS:

.screen-reader-only {
  position: absolute;
  width: 0px;
  overflow: hidden;
}

Conclusion

And now my website is accessible! Or, at least far more accessible than it was before. The next step would be to install a screen reader and try to navigate the site – screen readers aren’t cheap but there are some free ones out there, I’ll save that for another blog.

If you want to make your website more accessible, go ahead and download the Axe extension to see the damage.

And that’s pretty much all there is to it, if you liked this blog then please sign up for my newsletter and join an awesome community!

Leave a Reply