Thibaud’s blog

Notes, thoughts, and open-source software

Making Wagtail accessible

I recently gave a talk at Wagtail Space US 2019 about making Wagtail accessible – an ongoing effort over the last few months. The recording is available on YouTube: Making Wagtail accessible, with more notes / links available below.

Slides: Making Wagtail accessible – Wagtail Space US 2019

Please find the initial “blog” version of the talk below for reference.


From the Wagtail 2.6 release notes:

Wagtail now has official accessibility support targets: we are aiming for compliance with WCAG2.1, AA level. WCAG 2.1 is the international standard which underpins many national accessibility laws.

Wagtail isn’t fully compliant just yet, but we have made many changes to the admin interface to get there. We thank the UK Government (in particular the CMS team at the Department for International Trade), who commissioned many of these improvements.


There are many reasons

There are many reasons to care about accessibility!

For users of assistive technologies, using Wagtail’s admin interface is difficult (#4199). This is at odds with Wagtail’s general focus on user experience. For organisations choosing between CMSes, this might make Wagtail a bad option – because of concerns with equality in the workplace, and legislation that mandates compliance with accessibility standards[2][3][4][5].

It doesn’t have to be so negative

This initial problem statement is quite negative, and puts a lot of emphasis on procurement competitiveness and legal risks as motivations. We could also say that it’s important for Wagtail to be accessible, simply because we want Wagtail users to have a good experience, regardless of how they access Wagtail. And accessibility improvements for people relying on assistive technology usually also lead to usability improvements for everyone.

So there are many great reasons to care about accessibility, whether you want to see this in a pessimistic or optimistic light.

And it’s not just Wagtail

Not much specific to Wagtail here. Intranet, CRMs, ERPs, social media tools, business intelligence, Django admin.

Internal tools shouldn’t compromise on accessibility just because their audience is smaller.

What we did

We = a bunch of us. Not just me.


Compliance with WCAG2.1, AA level

  • Why WCAG2.1? Because it’s the basis of many national accessibility laws.
  • Why AA level instead of AAA? Because AAA compliance generally mandates a lot when it comes to visual design, and it didn’t feel realistic

Assistive technology support targets

Here is what we settled for:

Type Assistive technology
Screen reader NVDA on Windows with Firefox ESR
Screen reader VoiceOver on macOS with Safari
Magnification Windows Magnifier
Magnification macOS Zoom
Voice control Windows Speech Recognition
Voice control macOS Dictation
Screen reader Mobile VoiceOver on iOS, or TalkBack on Android

Like for cross-browser testing, having explicit targets helps a lot in understanding what to test. When choosing those targets, we tried to have a representative selection of assistive technology in use, but also choose tools that we could reasonably expect people contributing to Wagtail to install and test with. There are things not covered here, for example high-contrast modes, dyslexia fonts.

This is largely based on the results of the 2016 assistive technology survey by GDS (the UK’s equivalent of 18F?).


To assist with the auditing, and further testing. We picked a selection of tools centered on Axe, an accessibility rules engine.

  • Axe – Accessibility rules engine with support for WCAG & Section 508
  • Accessibility Insights – a set of accessibility compliance browser extenstions built upon Axe for automated checks
  • Pa11y – Command line tool for accessibility checks with Axe & HTML_CS
  • React Axe – integrated directly in our build tools, to identify actionable issues. Logs its results in the browser console.

GDS accessibility tools audit


  • Automated accessibility test suite with 100+ scenarios
  • Automated visual regression test suite, 87 scenarios (BackstopJS)

GitHub: thibaudcolas/wagtail-tooling


Main goal: understand where we are at, and create a backlog of improvements to improve the user experience / reach compliance. Both automated (cover lots of UI), semi-automated, and manual.

First, figure out what to audit. We made a big spreadsheet.

Screenshot of UI overview spreadsheet


  • Scenarios identified: 344
  • Scenarios tested: 189
  • Discrepancy between the two are for parts of the UI that are either:
    • Not used often
    • Hard to reach
    • Hard to test
  • Automated issues found: 336 🙀
    • This can feel like a big number, but there’s lots of duplicates here between different parts of the UI
    • Some of the issues are false-positives

But still, that’s a lot of issues


We made a big spreadsheet with the 336 automated test failures, and the manual ones too. I don’t think it’s that interesting to look at, so let’s just spend a bit of time auditing Wagtail together

Let’s look at some examples, first with a screen reader. What issues can we spot? Rapid fire.

On YouTube: VoiceOver accessibility testing: Wagtail 2.5 demo,

What we fixed

From 336 issues to 172, most of them on parts of the Wagtail UI we chose not to cover

Wagtail 2.6 release notes:

  • Better text-to-background color contrast across the whole CMS
  • Increased font size across the board as well
  • Added focus outline styles
  • Added more ARIA landmarks and refactored heading structure
  • Added a lot more contextual information to links for screen reader users
  • Fixed the icons implementation (more or less )
  • Fixed focus not moving to the pages explorer
  • VoiceOver accessibility testing: Wagtail 2.6 demo

Full release notes

What’s next

Accessibility should be part of the design & dev workflow for any UI changes, rather than an occasional one-off push

Contributors to Wagtail should have clear information on what to do to make sure they build accessible UIs

Work in progress: