Using Lighthouse to validate web accessibility

illustrations illustrations illustrations illustrations illustrations illustrations illustrations

Published on 17 August 2023 by Andrew Owen (8 minutes)

I’ve long been an advocate of localization, which is why it was important for me to make this site multi-lingual. But I’ve been an advocate of accessibility for even longer. So I really should have done an analysis on the site long before now, and for that I apologize. People tend to think that web accessibility is about disability, if they think about it at all. And then they do a quick mental calculation that goes something like: “How many users with disabilities am I going to have and how much time and money is it going to cost to make my site accessible?” And then, unless they are mandated to by law, they tend to do nothing.

Accessibility is something that you should embrace because it’s the right thing to do. But if you need to sell a reluctant manager on it then you’ll need to make the business case. Here you can take the “carrot-and-stick” (reward and punishment) approach. In the US, the Americans with Disabilities Act (ADA) applies to state and local governments and businesses that are open to the public.

In 2016 Guillermo Robles, who has a vision disability, brought a lawsuit against Domino’s Pizza, LLC, under the ADA. He alleged that the company’s website and smartphone app were not accessible for people who use screen readers (software that convert onscreen text to audio or braille). Specific barriers cited included lack of “alt text” for graphics and hyperlinks without text to identify their purpose.

Domino’s argued that the ADA does not apply to websites because the Department of Justice (DOJ) doesn’t maintain specific technical standards for web content, in violation of its Fourteenth Amendment right to due process. A district court dismissed the case, but the Ninth Circuit Court of Appeals came to a different conclusion. The Supreme Court denied a petition to overturn the Ninth Circuit Court’s opinion, establishing the precedent that the ADA applies to digital content. The case was finally settled in June 2022.

In non-legal summary, Domino’s spent a vast amount of money on lawyers to damage its brand through six years of bad press when it could have made its website accessible for a fraction of the cost. Another takeaway from the case is that the Web Content Accessibility Guidelines (WCAG) are the consensus standard for digital accessibility. The latest version (2.2) is currently in draft at time of writing.

That was the “stick”, now for the “carrot”. The Click-Away Pound Survey found that in 2016 more than 4 million people in the UK abandoned a retail website because of the barriers they faced, taking with them an estimated spend of $14.9 billion. By 2019 that figure had grown to $21.8 billion. In the UK alone there are an estimated 7.15 million people with online access needs, but the survey indicated that a mere 8% contact site owners about barriers they experience. So the onus is on businesses to ensure accessibility in the first place. But how to go about it?

First off, if you’re contracting out your website design, write accessibility into the contract. Ideally, the WCAG recommendations should be adhered to when designing and building a site in the first place. But the recommendations evolve over time, and like localization, it’s often necessary to retrofit accessibility to an existing website. Like translation, it’s not necessary to do it all at once. Depending on the scale of your site, you may need a business plan. You’ll certainly need a project plan. Start by tackling the most critical areas. In e-Commerce that would include:

  • Checkout
  • Form fields
  • Color schemes
  • Alt text
  • Mobile screens

There are a variety of tools available to check for WCAG compliance, but if you’re using Google Chrome or Microsoft Edge, you already have one called Lighthouse built into your browser. It’s also available as an add-on for Firefox (where you can access it from an icon in the top right of the browser). In Chrome and Edge, right-click on a page and select Inspect to bring up the developer tools. Then select Lighthouse from the menu. If you can’t see it, click » to show a list of the other menu options.

Historically, Lighthouse analyzed cold page loads. But since version 10, it can analyze and report on the entire page lifecycle using user flows. This enables you to analyze an entire web app. However it requires use of Puppeteer and the Lighthouse API. Some knowledge of Node.js would be useful. But you can get started with the standard functionality.

When you open the Generate a Lighthouse report page you’re given a choice of Mode, Device, Categories and Plugins. Different modes are useful for testing different things:

  • Navigation (default): Analyze accessibility immediately after page load.
  • Timespan: Measure layout shifts and JavaScript execution time over a time range including interactions.
  • Snapshot: Find accessibility issues deep within SPAs or complex forms.

Unless you’re using flows, you’ll want to concentrate on navigation and snapshot modes. When it comes to devices you should test both Mobile and Desktop. In the categories section you can select performance, best practices, search engine optimization and progressive web app. But I would recommend only selecting one at a time, starting with accessibility. Unless you’re using Google Ads, you can ignore the publisher ads checkbox under plugins. You can generate the report by clicking the blue button in the top right of the pane. It will be labeled according to the mode you selected.

If you’re doing analysis a page at a time, you should start with the most common use cases. So for my site that will be the blog landing page and an article that includes the most common elements, such as code snippets. The blog page scores 85/100 on the navigation report. It isn’t terrible but it could be better; anything less than 80 is bad but ideally you want higher than 90. It scores 12/15 on the snapshot report. Plenty of room for improvement. The blog article does much worse on navigation (78/100) but slightly better on snapshot (13/16). With luck, some of these problems will be common across the entire site and fixing them for these specific pages will improve the rating of the entire site.

It’s best to start with the “low hanging fruit” (easy fixes), and the easiest one to fix is low contrast colors. The site is getting quite complex at this point, so the easiest way to fix this was to add a new lighthouse.css file to the config to override any low contrast settings. This gets the blog page rating up to 88. It turns out the problem on the blog article is the Monokai syntax highlighting. There’s only one low contrast color, but it gets used a lot. Because the colors are set by a script, it can’t be overridden in CSS, so I ended up having to add some custom JavaScript to patch it. But that got the article up to 82. It took longer than it should have to fix because I forgot that style.color deosn’t return a hex color value.

function fixColor() {
    var spanElements = document.getElementsByTagName("span");
    for (var i = 0; i < spanElements.length; i++) {
        var element = spanElements[i];
        if ( == "rgb(249, 38, 114)") { 
   = "rgb(249, 72, 148)"

The next easiest fix was missing button labels. This was a deliberate choice on my part, because images don’t require translation. But they’re not very useful if you can’t make them out and your screen reader just says “button”. In this instance I used the button.ariaLabel property in the JavaScript that adds a copy button to code snippets. That was enough to get a blog article full of code snippets a 91/100 rating. There was also a warning that I had the maximum-scale attribute on the viewport element set to less than 5. So I set it to 5 and nothing broke. That got me up to a 100/100 score in navigation mode and 18/18 in snapshot mode.

Going back to the blog landing page, it gets a 98/100 in navigation mode and 14/15 in snapshot mode. It’s getting marked down because headings don’t go down a step at a time. It should only be a problem for a screen reader if a heading appeared out of sequence, such as starting with a heading 2, followed by a heading 1. I managed to get the same score for the homepage after I added some more parameters to the TOML file to ensure all the buttons had aria labels. After a few hours work, all the pages I’ve tested are getting a 98/100 or better in navigation mode, where some were previously in the low 70s. I think that was well worth the effort.

All told, I spent the better part of an evening fixing the site and testing. If you have an Apple device then you can say “Hey Siri, enable VoiceOver” to activate the screen reader and “Hey Siri, switch off VoiceOver” to deactivate it. I tried it out on my iPhone mini and iPad Pro and it was very useful for checking navigation and alt text. Crucially, when I was done the only visible difference to the site was a slight change of color scheme. Which was an improvement. I also had a look at a version of the site from a year ago on to see how it compared.

So you’ve made your website accessible. What now? I recently wrote about the value of analytics. You can use analytics tools to determine how long people are spending on different areas of your website. With careful evaluation of the data you can determine if people are abandoning certain areas, which could indicate that there’s room for improvement. And make sure you’re up-to-date with the latest WCAG recommendations.

But remember at the beginning I said that most people think accessibility is about disability. Specifically they often think about visual disability. But what about neurodiversity? Or indeed diversity in general. For example, people with English as a second language or non-English speaking (viewing the web using machine translation). This is where it helps to have a style guide and for your written content aimed at a diverse global audience.