How to Use the Wagtail Accessibility Checker

Hello y'all. I'm coming to you from my sister's basement this week. Uh I'm in Pittsburgh for PyCon US 2025. Uh, and I have a great place to stay, so please forgive the uh echoiness of my audio this week. I definitely wanted to make sure that I still did a video because May 15th is Global Accessibility Awareness Day and you probably have heard us go on about accessibility. at Wagtail before, we're really keen on making sure that people are aware of all the ways that they can make their content and their websites more accessible. So I thought it would be great to do a video this week on our built-in accessibility checker. So let me just go ahead and show you all how to use it. So right here we have a blog post.

Pretty standard test blog post here with a title, an image, and a few paragraphs of Laura Mipsum. Along with a few accessibility mistakes that I've introduced here. Now, where are those accessibility mistakes? Let's find out together. So the first way to access the accessibility checker in the Wagtail admin is to head up to this toolbars area here, and we're gonna go over to the checks area, and I'm gonna click that. And underneath our context, content metrics heading, here you'll notice that there's an area that says issues found And there have been three issues that have been flagged in my content. There is an empty heading, there is apparently an incorrect heading hierarchy, and also apparently I messed up some alt

text. Where did I make these mistakes? Well, it's you know I can just go back through my content if I wanted to and have a look through there. Uh but it's actually a little easier to use another view that we have for the accessibility checker. So I'm going to go back to the preview menu here and I'm going to open up the full page preview. And so you'll notice down here in the right hand corner we have a Wagtail edit menu down here, and also a big red three, which means that some accessibility issues were found. So if I open this menu and click on the accessibility item, you see the same list of issues that I saw in the checker view as well. But one extra thing that I have in this view here is that I can click on this kind of compass-looking symbol here

And it takes me straight to where the issue is on the page. So I know and things are a little bit squished up right now, just so you know, I'm filming on my laptop instead of my usual second screen setup here. Uh but so that's why, you know, you can't see things spread out uh as much as normal. But we have the Main image is clearly the one that's having an alt text issue. And if we click the next little compass symbol, apparently the heading issue is between the second and third paragraphs in my text. And then if I click here, I know that this heading right here, More Accessibility Facts, is the one that I'm having an issue with as well.

And so now that I have that information in my head, I can go ahead and head back over to my blog post and start think fixing things up. So let's close things up here to get a bit more room and scroll down. Yep, there is that empty heading right there. Kind of looks like there's something there, but there isn't. So I'm just gonna add what I probably intended to put there anyway, accessibility facts. So add that heading in. Now that heading is no longer empty. You can also just delete it to fix that as well. And then the one that's a little harder to catch is because you know everything looks normal here, but I know that there's an issue with this heading. So right here, this heading is an H2.

If I click down here and check the format bar up here, oh it jumped from an H2 to an H4. And that's not very good for screen readers. That's like removing a stair from a set of steps. Because screen readers love to go in order from H2 to H3 to H4 to H5 to H6. Like how many ever whatever levels of H you want to introduce. As long as they're in order, screen readers are happy. When you start skipping around, screen readers are not happy. And that's why we flag this issue in the accessibility checker. And let's go ahead and fix this. So we want to make this an H3 instead And I know it can be tempting to use a, you know, an H4

because maybe the font is nicer or the color is more what you're looking for. But definitely, you know, can consult your developer on that. that instead of using an H4. The people who use screen readers would very much appreciate you not messing with the structure When it comes to that. Alright, so those issues are fixed, but I still need to fix my alt text, and I'm gonna have to open another tab to do that. So let's edit this image. And so the issue with the way this particular website is set up right now is that when I have a title but no description. The alt text defaults to the title. And so in order to make and you know this is a terrible title for alt

text. It just tells me nothing about the image. It just tells me that it was generated by ChatGTP. And you know, nobody wants to hear a file name when they're listening to a screen reader output. So I'm going to go ahead and put a new description in here that is a bit more descriptive It describes the image as a cartoon of a blind man and a woman wearing headphones, looking at a computer screen with a accessibility symbol on it. And that is still a not the best alt text, but it is better than a file name. And that is something that will make this a much better experience for anybody who uses a screen reader on this page. Alright, I'm gonna save that and let's head back to our blog post again.

I'm gonna go ahead and save this draft so that everything refreshes and then I'm gonna go back to the checks section And voila, no more issues. Everything has been cleared. So those are some examples of some of the issues that can be found in content editing using the Wagtail Accessibility Checker. The checker is also very useful for catching code level issues as well. I definitely uh want to encourage you to head over to our Wagtail documentation. We have a big section on accessibility considerations. And even if you don't do anything at the code level, this is just really useful information on web accessibility. It's very well written. I highly recommend reading it top to bottom. But the key thing that I want to make sure that you don't miss is the list of checks for the accessibility checker.

So if we go down here under the section built-in accessibility checker, you can see the full list of tests That are included in the accessibility checker. And so you see that some of the ones that we just did demonstrated here, like the empty heading check and heading order, and also the alt-text quality check. But there are some code level checks as well, like checking button elements and making sure that your iframe elements have a text label, and catching things like using paragraph tags instead of heading tags. You know, that may if you are working on a template for a new Wagtail website, like being able to use this view here, I'm going to refresh it so that you know you can see now there are no more issues to be found.

But you can use this view as well when you're testing any of the websites that you're developing in Wagtail to see like, is there anything in my code that is getting flagged by the accessibility checker? And so that's another tool that you can use as you're developing your templates or updating your templates or doing a web accessibility audit. Is it you know that's something that an auditor can use as they go through as well just to catch some of those code errors? And you can make a list and be like, hey, we need to fix these things. All right. Uh I'm going to include a link to that documentation down in the video description. Please, please give it a read. I hope that this was a great lesson for y'all on Global Accessibility Awareness Day.

And if you'd like to learn more, please. Subscribe to our YouTube channel. I will definitely do more videos like this in the future. But also please consider signing up for our newsletter, which you can find at wagtail. org/slash newsletter.