axe-core VS accessibility-insights-web

The reports often rank the issues by severity level and provide actionable solutions. Using these reports, developers can prioritize accessibility fixes and improve their products' accessibility. Popular examples of automated testing tools include Axe, WAVE, and SiteImprove. Also, most modern browsers offer built-in accessibility audits within their developer tools.

‌Videos To caption videos, HTML is a great option. But if you are using markdown, you can embed videos from YouTube and Vimeo using the tag. These apps offer in-built caption support so you can enable captions before adding the embed code.

You could also install third-party plugins for this purpose.

Here’s another tip: avoid flashing content in your videos as it could lead to seizure triggers. If your video has flashing bright colours, ensure that it does not exceed two times within a second.

Add transcripts to audios and videos

It’s a good idea to add transcripts to your audio and video content. Not everyone will want to watch or listen to the content. But they may be curious to know what it is about.

By adding a transcript, you make it easier for anyone to navigate through the content and get the information that they need.

Transcript for audio
For audio content, you can insert transcripts using HTML.

Here’s an example:

 controls muted> 
   src="ringtone.mp3" type="audio/mpeg"> 
 

 
  
Here is a transcription of the text 
  00:03 = I am going to be productive today

 
  00:05 = I am going to be productive today

 
  00:08 = I am going to be productive today

 
  00:10 = I need to be productive today

 
  00:11 = I have to be productive today

 
  00:13 = I should be productive today

 
  00:16 = I am going to be productive today

 
  00:18 = I ought to be productive today

 
  00:21 = I have to be productive today

 
  00:23 = Productivity matters to me 

 

Enter fullscreen mode Exit fullscreen mode

For markdown documentation sites like Docusaurus, you can create a custom component.‌

• In your src/components folder, create a file named transcript.jsx.

• Insert this code:
  

import React, { useState } from 'react'; 
export default function Transcript({ }) { 
  const [showTranscript, setShowTranscript] = useState(false); 
  const toggleTranscript = () => { 
    setShowTranscript(!showTranscript); 
  }; 
  return ( 
    <div> <a href="#" onClick={toggleTranscript}> { 
    showTranscript ? 'Hide transcript' : 'View transcript'
    } 
    </a> {showTranscript && ( 
 (insert your transcript text here) div> )} 
    </div> 
  ); 
}‌

Enter fullscreen mode Exit fullscreen mode

• Go to your markdown file and import it.

import Transcript from '@site/src/components/transcript'; 

Enter fullscreen mode Exit fullscreen mode

Note: I added some tweaks to the code to make transcript display optional. You can edit it if you want the transcript to show as the page loads.

Transcript for video
Now for videos, YouTube is a great option. It provides inbuilt transcripts for your videos. So, you can always embed YouTube videos in your docs.

The transcript is in the video description after the main details. The transcript will display with the timestamps when you click the “Show Transcript” button.

Add code snippets and use the colour contrast technique

How to add code snippets
Use code blocks within the text to explain code instead of images. You could also use code snippets to showcase the output of your code. Unless it is necessary to add an image, you should use code snippets.

For instance,

index.html

 
   
    
     
    A calculator app 
     
    
    
    
  

Enter fullscreen mode Exit fullscreen mode

This will allow screen readers to read through the code, which they are not able to do with screenshots.

Colour contrast technique
The colour contrast technique implies using colours that are opposite or heavily contrasting.

For example, using black text on a white background has a high contrast, as opposed to using light brown text on a brown background.

When combining colours, you could use an accessible colour palette like Color Safe.‌

Add translation options

There are documentation sites that provide translation options where you can build your docs in multiple languages, websites like Jekyll. This is an example.

Docusaurus is also another doc site that provides multilingual options using Crowdin or Git.

• Follow through this guide to set up translation and localization on Docusaurus using Git.

• Follow through this guide to set up translation and localization on Docusaurus using Crowdin.‌

Use accessibility testing tools

There are tools you can use to check for errors in accessibility in your docs. Some examples are WAVE (Web Accessibility Evaluation Tool) and AXE (Accessibility Engine).

Also, you can get the NVDA(NonVisual Desktop Access) screen reader to test out your content. This software will let you know how the content of your documentation will be perceived by a user using a screen reader.‌

Set up an improvement or suggestion box

Finally, it may not be possible to cover the needs of every user. So you could add a suggestion or improvement box, allowing users to send feedback about how you could further improve the content. Hearing firsthand from users can help you know how best to make the docs accessible for them.

To add an improvement box, you could use an external form link that stores the users’ inputs or you could set up the suggestion box in the docs.

How to add an external form link in Docusaurus

You would need to create a custom component for that.

• Go to src/components folder and create a file feedback.jsx.

• Add this code:
  

import React from 'react'; 

export default function FeedbackButton({ href }) {
  return ( <a href={href} target="_blank" rel="noopener noreferrer" > Give Feedback </a> ); 
}; 

Enter fullscreen mode Exit fullscreen mode

• In your markdown file import it:

import FeedbackButton from '@site/src/components/feedbackbutton';

Enter fullscreen mode Exit fullscreen mode

• Insert the link

Enter fullscreen mode Exit fullscreen mode

When you run it on your docs, it should showcase a link to Google forms. Google Forms is an example, you could add the link to your company website or server.

Here’s what it’ll look like:

Summary

To follow and implement these accessibility best practices, you can consider creating or using an already made style guide. This can help you consistently implement these practices and make it easier for you and other technical writers on your team.

There are style guides focused on accessibility for technical writers, such as the following:

• Accessibility style guide by Heyawhite

• Write accessible documentation by Google for developers

• Writing for Accessibility by MailChimp content style guide

That sums up my tips about web accessibility practices in writing. I’m a technical writer, and you can reach out to me on Instagram or hire me via Upwork. Thank you for reading.‌

To measure or rather estimate accessibility, we can use automated audits like WAVE, axe and the accessibility report in Lighthouse or PageSpeed Insights to ensure that we don't violate essential Web Content Accessibility Guidelines (WCAG)

axe-core licensed via MPL 2.0: https://github.com/dequelabs/axe-core

Here is the BrowserStack extension:

[ ] Checked with axe DevTools and addressed Critical and Serious issues?

axe-core - To detect violations on page level.

Like auditing WCAG compliance with accessibility tools like axe and WAVE, it has become much easier to measure and provide data about the ecological impact of web development, but there are still a lot of unknown figures.

Axe is a set of tools created by Deque, to provide a solution for a testing library. To use Axe, one of the possible ways is to install Axe DevTools, which is a browser extension that provides you with a way to test your applications for accessibility issues. To start testing for accessibility using Axe DevTools, you just open the browser's Developer Tools, navigate to the Axe DevTools tab, and run an analysis on your desired webpage;

Hi Roy,

Thanks for sharing! I think it's great that more orgs/folks are trying to make the Web more accessible.

I'm also a web dev with some experience, and I've done a few accessibility projects, both in-house and with third-party consultants.

My main feedback is this: I would've loved to have been able to outsource to/partner up with experts for more of that work, but that would've been difficult at your prices. €2k-€4.5k/mo was between half and all of my salary as a full-time dev (working for small biz). On an ongoing basis, that would've been quite unaffordable.

If you're truly interested in making "accessibility achievable and affordable for organizations of any size", might you consider a pricing model where it's X dollars for the initial work (where the bulk of it lies, in terms of initial design/audit/etc.), and then a lower Y dollars/mo for maintenance (reviewing some new content and pages, etc.)? Possibly also some sort of allowance/sliding scale for smaller sites or smaller orgs?

In my experience, much of the work is frontloaded. Having to pay the same price month-to-month where subsequent months might not be much work at all is a tough sell. And in my experience, all-included subscription services like this often tend to be "best effort" anyway, especially for smaller customers who are competing for limited dev/design time with your bigger clients. At lower monthly costs, that's still a fair enough value proposition, but at four-figures a month... that's easily the territory where smaller companies might consider in-housing instead. And sure, people could subscribe for just a month or two and then cancel, but that feels disrespectful/dishonest.

In the past accessibility projects we've done, the upfront audits cost a few grand on a mid-sized site. We were presented with various reports and tables (several tens of pages worth), but it was really just a checklist of things we'd go down and address. The actual fixes took about a week of dev time. Then on an ongoing basis, we just followed the same recommendations for our new content, occasionally using free tools like Microsoft's free Accessibility Insights (https://accessibilityinsights.io/) to double-check our pages for problems. These days a lot of it is built into IDEs too.

That's not to say automated checklists are sufficient and can replace human expertise (yet), but they do take care of a lot of the low-hanging fruit, especially for ongoing content updates that follow the same format as previously audited pages/sites.

Now, the above was just my personal experience primarily working for small biz and nonprofits. If you're primarily targeting bigger enterprises or early 2020s-style startups with infinite money, and purposefully trying to exclude smaller customers, that's totally valid and maybe that pricing makes sense? (It's probably cheaper to them vs hiring AAA labor in-house). But for smaller orgs, your prices are often more than their entire website budget and nearly as much as an additional staff person. If you truly want to target them as well, would you consider something that's more suitable for their budgets?

---

Altogether separate than the pricing thoughts: It would also be lovely to see some demo reports/audits, or before/after screenshots etc. This is the sort of endeavor where the quality of consulting/auditing can vary a lot between service providers, and being able to see examples of your previous work would mean a lot.

---

Thanks again for sharing, and I hope this feedback wasn't too harsh! Just my 2¢ as someone who wishes more companies would voluntarily take this work on.

(I'm a frontend dev, but I came into the design side only later in my career, after having started as a full-stack programmer.)

I think this book is probably the single best resource I've seen on the topic: https://www.refactoringui.com/

It's a really easy-to-use format (one quick tip on each page, with clear examples).

It's from the people who made Tailwind, a CSS framework that's basically a reimagining of Bootcamp for the Javascript/component era.

Check out some of their templates: https://tailwindui.com/templates

These are lookalike "modern" designs that you can pay to use, or just draw inspiration from. Imitation == flattery and all that.

Along similar lines, check out the free Next.js templates: https://vercel.com/templates/next.js

If you want to build up from components instead, Tailwind offers a component library too: https://tailwindui.com/components

For React, I prefer the astoundingly good MUI framework (amazing components with lots of customizability, a good enough default look, and great documentation): https://mui.com/ If you end up going this route, using their Figma kit (https://mui.com/store/items/figma-react/) plus the Refactoring UI book from above should allow you to whip up a pretty standard-looking, "pretty enough" design in very little time. And then implementing it using the actual MUI lib would just take a few days.

There's also Ant Design: https://ant.design/

And Chakra UI: https://chakra-ui.com/

-----------

For more theoretical stuff (i.e., less visual but still very valuable), the UX research group Nielsen Norman still has a treasure trove of valuable advice: https://www.nngroup.com/articles/top-ten-guidelines-for-home...

You should know the basics of accessibility (beyond general usability, this alos means alt text, header levels, contrast ratios, readability, screen readers, keyboard navigation, special considerations for the hard of sight and hearing, etc.): https://www.w3.org/WAI/standards-guidelines/wcag/ or at least use an easy checklist tool like Microsoft's WCAG analyzer: https://accessibilityinsights.io/

Microsoft makes a very helpful Chrome and Edge plug-in that checks your site against WCAG 2.1 AA recommendations. Run it and fix the issues one by one and you're like 80% of the way there.

https://accessibilityinsights.io/

The other 20% is often like judgment calls on navigability and readability on screen readers. You can install one (or several) and try to navigate your site and menus using them. They are often free, especially the ones built into major operating systems.

If you just go down the checklist and do what you can, you'll be way ahead of most websites: https://webaim.org/standards/wcag/checklist

Microsoft also has a great interactive test that can probe your website for you and highlight issues: https://accessibilityinsights.io/

I think similar but less powerful checks are also built into some IDEs (Jetbrains) and linters (Eslint).

I really like the suggestions from other commenters here, WAVE, Axe, and Google Lighthouse are great automated tools. I'd also recommend SiteImprove and Microsoft's Accessibility Insights for their automated offerings. I have some further suggestions should you also want to go deeper into learning and addressing accessibility best practices.

Accessibility Insights Accessibility Insights is a free, open-source tool from Microsoft that allows you to test the accessibility of your website. The tool can be used as a browser extension or integrated into your testing framework. Accessibility Insights provides automated testing and manual testing features to help you identify accessibility issues on your website.

Accessibility Insights from Microsoft

Accessibility Insights - Tool to test accessibility from Microsoft (free)

Chrome Devtools is a great one to use for testing, I'm also really fond of Siteimprove and Accessibility Insights too. I'd also urge you to try a bit of manual testing as well, for example I noticed I was unable to effectively navigate using keyboard alone because I couldn't easily tell what links had focus when I hit the tab key. This article Focus management and inert is a great primer on the subject.