Making Wagtail Accessible for users with disabilities

[mush42]

Hello everyone,

After reading the docs, I've decided to use Wagtail on one of my personal projects.

Since I'm blind, I've discovered that my experience on editing content would be rather unpleasant, because the admin interface of Wagtail has some accessibility problems.

For example, the icon-font being used in the admin is not screen-readers friendly, it keeps adding random letters wherever it is used. This happen because it doesn't use the safe-unicode character range. This could be resolved by a simple javascript function which hides the icons from screen-readers.

Proposal:

Making Wagtail an accessible content management system. By adding necessary markup (and scripts) to wagtail's templates and outputs.

Goal:

Enable the users of Assistive technology to efficiently manage and edit content in a Wagtail powered site.

Rationale:

"It is essential that the Web be accessible in order to provide equal access and equal opportunity to people with disabilities. An accessible Web can also help people with disabilities more actively participate in society. Also, web accessibility is required by laws and policies in some cases." --- Web Accessibility Initiative (https://www.w3.org/WAI/intro/accessibility.php)

Execution:

I'll make a list of each area of Wagtail that may need some accessibility related fixes, and open an issue for each one.

Questions:

• Is openning issues is the preferred way? or should I fix it myself and create a pull request?
• If yes, how pull request should be structured? in a batch or on a feature by feature bases?

Regards,

[thibaudcolas]

Hey @mush42, thank you for reaching out and taking the time to write such a well thought-out issue. Making Wagtail accessible is something we care a lot about, even though I don't think we've stated it formally so far.

Generally, I think what we need first and foremost is to be told what to do and to define some standards for current and future developments (and enforce them in pull request reviews). This could take the form of some documentation and/or automated tests. Then, there are the existing problems with the admin, where it would help us tremendously if you took the time to give us your take – and then helped us prioritise what to fix.

The approach I would advise is:

1. For you to first make an audit of all the issues you encounter, listing them here.
2. For each, Indicate how problematic it is.
3. Then we can discuss how best to address them, and make separate issues / pull requests for each problem (the smaller the PR, the easier for us to merge it)

You're more than welcome to make pull requests, but I imagine it would be quite an undertaking to fix everything. I would advise you to first define what to do – then it'll be easier for others to contribute too.

---

Here are specific issues we're already aware of:

• Certain colours combinations not validating against WCAG AA #2224 Certain colours combinations not validating against WCAG AA
• Convert icon font to SVG: make icons screen-reader friendly and easier to update #1224 Convert icon fonts to SVG (not just for accessibility reasons, but that's definitely part of it)

I've just added an Accessibility label to these, and we can use it for future issues as well.

Finally, I should mention that we are in the process of changing the rich text editor within Wagtail from Hallo.js to Draftail. That is, don't bother auditing Hallo. And hopefully the new editor is better than the old one accessibility-wise.

---

Thanks again for raising this. Personally making accessible software is something I care deeply about, and I'm super happy at the perspective that we could improve Wagtail's usability.

[tmsndrs]

Huge +1 for this.

I'm hoping we can move to a more component based and documented front-end for Wagtail with some clear a11y requirements for component acceptance. Our biggest barrier to this at the moment is front-end input to Wagtail in general as it's a big task.

[renestalder]

I can help here if you're interested. Either testing or implementation. Got my focus on accessibility and can test on Windows NVDA, Android TalkBack and iOS VoiceOver. Also can share advanced techniques we got from accessibility audits made by third parties and tests with users.

[mush42]

Hello all,

I'm thrilled to receive such a positive feedback from the community, and feeling this strong passion for accessibility just make my hart bounce. So, lets start the real work, and brace your self for a rather lengthy comment!

What to expect?

In response to @thibaudcolas comment, I'll be listing the issues I'm facing while using Wagtail. The issues will be based on my personal experience as a user of assistive technology, so no automated accessibility testing will be involved. The issues will be mainly focused on managing the site and editing content in the admin interface.

The issues will be divided into classes according to their severity and how much they impact the end-user experience. For instance, the (class-1) issues have the biggest impact on usability, (class-2) issues have lesser importance than (class-1) issues, but they are critical nonetheless.

For each issue I'll write a brief description, list possible remedies, and link to additional resources from the web, in order to make this issue a reference for all subsequent issues.

Technical Details

Wagtail

I've installed the current version of Wagtail from Pypi, which at the time of writing is (1.13.1) into a virtual environment on a dual-core laptop running Microsoft Windows 10. The standard wagtail start command was used to create a new project, and Mozilla Firefox version 52-esr (extended support release) is being used to access the site's admin interface.

Assistive Technology

To access my computer, I use NVDA, which is a free and open-source screen reader for the Microsoft Windows operating system. A free copy of NVDA can be downloaded from it's website at (http://www.nvaccess.org/).

The recommended setup for accessibility testing and evaluation is NVDA + Firefox. But since the latter is going through a period of major revamping, it's current version (Firefox v. 57) doesn't play well with screen readers, so we resort to the ESR release.

A Note on Chrome

Chrome has a built in accessibility checker in its developer tools, but I haven't used them, nor I use chrome in general. But I hear that it has an excellent level of support for assistive technologies on Windows.

Note on references:

At the end of each topic I'll list a number of articles for reference, while this is not necessary for simple bug fixes, it is important to read them before undertaking any large effert.

Here is a list of sites and articles that are useful for any future work in the area of accessibility:

General References

• How to use NVDA and Firefox to test your web pages for accessibility
• Web Accessibility Checklist
• Accessibility - MDN
• WebAIM: Web Accessibility In Mind

Tools

• Accessibility Bookmarklets
• Ally.js, A JavaScript library simplifying certain accessibility features, functions and behaviors

Accessibility Issues in Wagtail's Admin

Class-1 Issues

1. The Icon-Font:

The icon font being used is very problematic for users of screen readers, because it uses actual letters and punctuations as place holders. While these letters are visually replaced by the real icons when the font is loaded, they are not hidden from screen readers. This makes it difficult to identify links and buttons when navigating the admin. For instance this is what I hear when I focus different links in the left sidebar:

- vPagesn
- oImages
- rDocuments
- aSettingsn

Approaches to resolve this issue might include:

• The resolution of (Convert icon font to SVG: make icons screen-reader friendly and easier to update #1224 ) which will automatically replace the icon font by something better for all users
• Moving the icons to their own inline elements, and hiding those elements from screen readers using javascript by setting their elements' aria-hidden attribute to true. A code example follows:

Instead of :

<a href="/admin/pages/" class="icon icon-folder-open-inverse" data-explorer-start-page="1">Pages</a>

It could be:

<a href="/admin/pages/" class="" data-explorer-start-page="1"><span class="icon icon-folder-open-inverse"></span> Pages</a>

And in javascript:

$(document).ready(function() {
  $("span.icon").each(function() {
    $(this).attr("aria-hidden", "true");
  })
})

Additional resources regarding icon fonts and screen readers:

• Bulletproof Accessible Icon Fonts
• How Can I Make My Icon System Accessible? - CSS-Tricks
• Font awesome is screen readers friendly

2. Navigating Page Content

To explore the content of a web page, users of assistive technologies rely on two pieces of information:

• The document outline, as indicated by its heading structure. Heading-1 is assumed to be used for the main title, heading-2 is for the subtitle, and so on.
• The use of Landmarks to identify major parts of the web page, e.g: navigation, main, footer, form...etc.

Unfortunately, Wagtail doesn't score well on neither of those, this makes navigating the admin pages using a screen reader very cumbersome.

Approaches to resolve this issue might include:

• The use of headings should be restricted to only real headings (i.e don't use headings for stylistic purposes)
• Add headings to indicate areas of interest (e.g current page title, title of form groups..etc)
• Identify major areas of interest in the page by the use of landmarks, either by using the new HTML5 elements (e.g: nav, main, aside, footer), or by explicitly adding the role attribute to each container element (e.g: role="main").

Additional readings on the importance of proper heading structure and landmarks:

• Headings - Page Structure - WAI Web Accessibility Tutorials
• HTML 5 and ARIA Landmarks
  • Improving access to landmark navigation - The Paciello Group

3. Add textual labels to icon-only elements

Some actions on the admin are available as icon-only links, such as the ordering actions found in the table headers. In this case, the screen reader doesn't speak the name (label) of that link, so the user would not be able to identify what the link does.

Approaches to resolve this issue might include:

• Use Bootstrap's "sr-only" class to add a hidden textual description. For instance, instead of:

<a href="/admin/sites/?ordering=name" class="icon icon-arrow-down-after"></a>

It could be:

<a href="/admin/sites/?ordering=name" class="icon icon-arrow-down-after"><span class="sr-only">Order by name</span></a>

• Use the aria-label attribute on the element to add a textual alternative to the icon. For example:

<a href="/admin/sites/?ordering=name" class="icon icon-arrow-down-after" aria-label="Order by name"></a>

Additional readings on the importance of textual alternatives:

• The Visual-only icon problem

4. Proper Focus Management:

Blind people rely entirely on the keyboard to access their system, so the mouse is out of the question. They use Tap and the arrow keys to find their way around, while the browser respond to these navigation commands by setting the keyboard focus on each element according to its tabindex.

For custom components, focus management should be done programmatically using javascript. Consider the following scenarios:

• After clicking the Pages link in the left sidebar, a sub menu opens, but the screen reader user is unaware of its presence, because the keyboard focus remains in the original link that was clicked.
• If you want to embed an image in a page, a file browser dialog opens, again, the user is unaware of its appearance because the focus is still.

Fixing this issue requires additional work in the client side code, specifically, prgramatical management of keyboard focus.

Additional readings on the topic of keyboard focus management:

• Keyboard-navigable JavaScript widgets - Accessibility - MDN
• WebAIM: Keyboard Accessibility

[tomdyson]

@mush42 I'm sure there will be many more detailed responses to your comments here, but in the meantime: thank you very much for taking the time to write this constructive, thoughtful and educational review.

[thibaudcolas]

Thank you for the detailed review @mush42.

I think we should tackle the icons first since it's at the top of your list, and has been on our radar for a while. Adding this to our roadmap for the 2.1 release. The main piece of work here (and for their conversion to SVG at #1224) is that the icons are used as CSS classes on arbitrary elements instead of being componentised. We started doing this for the React Icon implementation, but not in HTML. This isn't that big of a refactoring, we'll just need to make sure there are no visual regressions. Once this is done, it will be easier to rework the icon implementation to make it screen-reader friendly, and later change it to SVG.

@renestalder would you be willing to contribute to the icons rework? I have basic experience with accessibility, but not much with testing it (beyond using VoiceOver). Could use help developing and testing the new version. In particular it would be really helpful if you could help us set automated tests / linting for accessibility matters so we have some baseline checks in place.

---

Looking at the other issues, I think "Navigating Page Content" would be the hardest to address. The Wagtail UI code is notoriously hard to refactor, so any changes to the document outline are likely to cause breakage. @mush42 are there specific pages you think we should prioritise here? I think it may be easier to address page by page, or section by section.

For focus management, I'll have a look at the Pages / Explorer sub-menu. It already has some focus management in place so this should be an easy fix (@renestalder any experience testing these types of modals?).

[mush42]

Hi @thibaudcolas,

A pragmatic (and dirty) fix for the content navigation issue is to use aria properties on the existing markup, without touching the document outline. For instance, we can add a role of heading to a "div" element with an aria-level of 1 and the screen reader will consider it a perfectly normal "h1" element. An example follows:

A hypothetical, semantically inaccessible, element.

<div class="styled-as-h1">Pages</dive>

The pragmatic fix, which results in a semantically accessible element:

<div class="styled-as-h1" role="heading" aria-level="1">Pages</dive>

=========
Since you have mentioned menues, it is critical to add necessary aria states and properties to make their semantic meaning clear for people using assistive technologies, because an "ul" element has no semantic meaning other than that it is an unordered list.

For this to happen, a role of "menu" should be added to the parent menu element, and its aria-expanded attribute should be set to either true or false depending on the initial state of the menu, and the aria-expanded attribute should be toggled via javascript as the menu state changes. An example follows:

< ul class="collapsed" role="menu" aria-expanded="false">
...
</ul>

[renestalder]

would you be willing to contribute to the icons rework? I have basic experience with accessibility, but not much with testing it (beyond using VoiceOver). Could use help developing and testing the new version. In particular it would be really helpful if you could help us set automated tests / linting for accessibility matters so we have some baseline checks in place.

@thibaudcolas Sure. To be honest here, I didn't do automatic tests yet, we did this manually all the time, with browser addons like Lighthouse and the screenreader tools directly. But those browser addons or their core also exists as CLI, so it shouldn't be a problem to get this into the front-end tests.

[thibaudcolas]

👋 just a quick update that this hasn't fallen off the radar. We're busy with the big Wagtail 2.0 release, and once this is out I'll move onto the icons rebuild.

@renestalder could you have a look at the React implementation of the icons (used in Wagtail's "Pages" explorer menu) and let us know how you think it fares accessibility-wise? We tried to implement it with screen readers in mind, but I'm not sure whether we actually succeeded.

---

On the automated testing front, I tried a few tools and settled on aXe for now. It's not the best in terms of number of issues found, but it has the advantages of being free, easy to integrate in our testing suite, and it doesn't ever report false positives.

[renestalder]

@thibaudcolas Just from the code of the icon component, this looks totally fine to me, as long as you make sure, you have a textual representation of the icon outside of the component or by making the title property of the component itself required. Just make sure you never serve an icon without a textual representation.

[mush42]

@thibaudcolas @renestalder If the icons are there for presentation (only) purposes, then it is not necessary to provide textual description. Otherwise, if the icons are used by themselves to convey a piece of information, it is critical to provide an alternative text.

[thibaudcolas]

We now have an accessible icon implementation in Django, thanks to the work of @SanderTuit in #4381 (based on the React implementation I linked above). The next step is refactoring as many of the icons in the admin as possible to this new implementation, while making sure this doesn't cause style regressions.

I'll attempt to do this for the sidebar this week, if other people want to tackle other parts of the admin as well it would help a lot. Wagtail 2.1 is scheduled in about a week, it would be really cool to have some of the icons switched over by then.

[raq929]

I'm going to work on number 2, Navigating Page Content, during the Wagtail Space US sprint.

[thibaudcolas]

👋 I'm going to be working on accessibility fixes for some of the Wagtail UI over the next few weeks. The plan so far is to do an initial audit of as much of the UI as possible, set up some tooling (#4871), then deliver as many fixes as possible, aiming for Wagtail 2.6 (prioritising things that are big blockers like what's been mentioned here).

If you're interested in helping with this, there is an #accessibility channel on the Wagtail Slack. Please come by and join the conversation!

[thibaudcolas]

As part of my current accessibility work, I decided to invest a bit of time to write a formal proposal for how I think accessibility should be handled by Wagtail as a project.

Wagtail uses RFCs (Request For Comment) for this, via pull requests so they can be commented on. Here is the one I just published: wagtail/rfcs#37.

This is quite high-level, and obviously a lot of the tasks listed in there are in motion already, but if accessibility is something you care about please go have a look and comment.

[thibaudcolas]

I've started creating separate issues for each of the problems initially reported by @mush42 (#4199 (comment)). We've given these a higher priority as part of our current work, since they are well defined and their resolution is critical for screen reader users to be able to use Wagtail. Here are the individual issues:

• 1. The Icon-Font: Convert icon font to SVG: make icons screen-reader friendly and easier to update #1224, SVG icons refactor + SVG icons for menu #4821, Change icon font implementation to be screen-reader friendly (#1224) #5359.
• 2. Navigating Page Content: Define more ARIA landmarks in the CMS admin #5275 for landmarks, Improve heading structure in the admin for screen reader navigation #5276 for headings outline
• 3. Add textual labels to icon-only elements: Make sure all actions in the CMS have a textual label relevant to screen readers #5274
• 4. Proper Focus Management: Focus should move to the Pages explorer menu when open #5336, Implement focus management in main menu #5337, Implement focus management for chooser modals #5338

We've identified many more accessibility issues, but at this stage we're choosing to only add things to the issue tracker once they are part of our backlog. I won't be posting all of the issues here – if you want to keep track of what's covered, please have a look at the corresponding “WCAG2.1 AA compliance” project board and “Accessibility” issue label.