Accessibility audit and shepherd for making improvements


My name’s Kevin Robinson and I work at the Teaching Systems Lab at MIT. We work in K12 teacher development, and have been experimenting with using Discourse as a companion to our online EdX courses (eg., Design Thinking for Leading and Learning). It’s gone well and we’ll try this again for some courses this fall. If other folks are curious, here’s our open source Discourse plugin that lets EdX users jump directly into Discourse through LTI.

We also have the benefit of having an amazing accessibility team with us in MIT’s Office of Digital Learning, and Mary and Rich in particular have been generous enough to do an accessibility audit on our Discourse instance. They helped flag some things we could modify on our own right away, but also found some things that look like they’d impact accessibility for most Discourse instances. This seems like a good opportunity for us to try to contribute back upstream and have our work impact the many Discourse instances around the world.

Some of these changes are pretty straightforward (eg., improving default foreground-background colors so they have more contrast, changing <b> tags to <strong> so that they’re semantic, adding in some ARIA tags to the message thread UI so that folks using screen readers can scan through messages and replies with less noise). Others are probably more involved or touch hot parts of the codebase (eg., removing nested tables on the latest post section since they’re particularly problematic for folks using screen readers, notifying screen readers of AJAX updates to the page that are only indicated visually right now). In total we’ve identified ten issues to focus on and what we think it’d take to address them.

What we’d love to be able to do is share this audit with someone who would be able to help guide us as we do the work to make some of these improvements over the next few months. I’ll be doing the engineering work, and have lots of experience working with Rails and JavaScript, and a little experience with Ember and Discourse. We’ve got some engineering time to give and a course launch in late September, and so we’d like to see how many of these issues we can get shipped before then, even if it’s not all of them. Our pace probably will be relatively slow, but we’ll definitely put some work in on this if someone can help out with guidance and reviews when touching the trickier or hotter parts of the codebase.

As far as I can tell, there have been a few threads about accessibility on (one, two, three, four, five, six, seven, eight, nine). Please point me elsewhere if there’s more I can read up on first, but I see lots of love from @sam in particular about accessibility work if it’s expressed as actionable steps. Based on those threads, I’m pinging @sam and also @downey @cpradio @TechnoBear to see if any of you all could help test or shepherd any work we do here.

Let me know what you think, we’d love your help to amplify the work we can put in here so it can help other Discourse instances improve their accessibility as well.



This sounds fantastic! Thanks so much for putting this together!

I would focus on the lowest hanging :apple: :grapes: :tangerine: fruit first.

1 Like

Just to add: everything here sounds great with one minor exception.

I would say I am quite opposed to changing <b> to <strong> since I feel that’s a trivial, noisy change that has no real meaning and massive downside in terms of payload size and breaking changes to CSS rules; these tags are synonyms and <strong> is way too verbose. But the rest sounds amazing!

Awesome, thanks @codinghorror! I’ll share the audit here next week, in the order that we think would make sense to tackle these, and then try to get a first improvement done in the next two weeks, and then go from there. :slight_smile:

re: <b> and <strong>, the accessibility experts I work with included this in the prioritized list of changes recommended from their audit, so for them the change is meaningful :slight_smile: I’ll find out more about why and include that in the write-up (I assume not all screen readers respect <b> but I don’t actually know). This is also why it’s so helpful to have input from you and other Discourse folks so that we can find the right tradeoffs and track down those details like the style rules that would be impacted when submitting PRs.

Thanks again for your openness!


Hi Kevin,

Wondering if there are any specifics you would like us to address, we are always keen to make Discourse more accessible!

I would love to see a copy of the audit!


I would like to second the request to publish the audit, and for a shepherd on the Discourse team to begin to think about how accessibility changes could be incorporated.

I’m one of the admins on a project that wound up with two forums (OpenWrt/LEDE - long story, not worth repeating here.) One forum uses punBB, the other Discourse.

There is so much to like in Discourse, that it’s hard not to standardize on it. But at least one of our significant contributors finds Discourse very difficult to use with his screen reader, and he is quite reluctant to use it.

A year ago when we set up Discourse, I told him that a review of this forum made it sound as if accessibility changes might be in flight. It would be wonderful if 2018 would be the year for it. Thanks for listening.


I would love some direct feedback from your contributor, anything specific we can address?


Hi @codinghorror and @sam,

Apologies on the delay, the timing here did not work as I had hoped when first bringing this up, but let’s try restarting!

Here’s a link to the top items that came out of the accessibility audits I mentioned. It’s a Google doc, with the idea being folks could comment to clarify on that doc and bring bigger-picture discussion back to this Discourse thread. Feel free to suggest a different process and I’m happy to shift to that too!

There’s almost certainly items in there that need clarification, and ones that will be simple and straightforward (eg, color contrast) while others might need more discussion and shepherding :slight_smile:

Thanks, and let me know what you think makes sense! It’d be great to create some momentum and maybe tick off an item or two in the next week or so.



Let me try to help out here:

In the Banner, and in the Reply field (the pop-up that comes up to remind you of discussion etiquette), you cannot dismiss the banner nor make the warning go away without the use of a mouse. This must change as it is what we call a keyboard trap. There should be a way to give the dismiss X keyboard focus and actionability.

I am pretty sure that ESC works when a popup shows up on reply. Which banner are you talking about?

—> There are some contrast insufficiencies where you need to increase the contrast. The 2 most important ones to fix are:

  • The text that appears for posts

  • The Reply field Area Text

Both have a color combination of #919191/#ffffff, which has a contrast ratio of 3.15, which is not sufficient. At this size, you will need a ratio of at least 4.5. Consider using the following foreground/background combination: #767676/#ffffff / has a ratio of 4.54

Reference: the Tanaguru Contrast Finder Tool:;jsessionid=AA609C7DCDEC027124D57CBEC05DA090?foreground=%23919191&background=%23FFFFFF&ratio=4.5&isBackgroundTested=false&algo=Rgb

This can be improved by setting colors for an instance, but ideally the default setup upstream would be accessible as well.

I am not following here, can you post a couple of screenshots

Actually the more I read through this the more I feel we need specific topics on particular issues with examples, cause its very very hard to untangle this here without examples and screenshots.

Any chance you can make dedicated topics for the top 3-4 issues here on meta? Then we can work through them and continue to the next issues?


I get this one - it’s the placeholder text (below) that appears in the composer before anything is typed. That text is #919191.

Type here. Use Markdown, BBCode, or HTML to format. Drag or paste images.
1 Like

Do we really need to touch that? That text is merely an embellishment, giving it great contrast risks people not being able to tell they can enter stuff in the text area.


I will advise our contributor that this interest has arisen, and invite him to this conversation. Thanks!


Hi I am the bloke from the LEDE and the OpenWRT forums. I am blind and use a screen reader called NVDA to access the internet. I will help out where I can but I don’t know much about html5 or what ever language Discourse is in, but I will try to explain how things effect me as a screen reader user. The thing I don’t like about Discourse the most is that I cant jump through the posts with my keyboard. To give you the best idea of how that would work for me I will have to compare the OpenWRT forum to this one. So here’s my work flow from when I log on to the home page of the OpenWRT forum. If any one wants to install the free screen reader NVDA you can follow my steps and see just how hard it can be to use a Discourse forum.
Step 1:
I load the page at:

Step 2:
I use the H key on my keyboard to jump through the headings on the page until i get the one i want, in this case it’s the one that says “General Discussion”
This takes 4 presses of the H key to get me to were i want to be and then i press enter.
Step 3:
I can now use my H key to jump through headings again down the page and each time I press H it reads out the topic title. I jump to a thread I want to read or reply to and press enter.
Step 4:
I then can use my H key to jump from post to post up and down the page in order and every time i press the H key it will read out the post number. That lets me know were about I am in the thread. The verry first heading I get on any thread on the openwrt forum will say how menny posts are in the thread EG
In the thread called “KRACK Attack against WPA2” it says “Posts: 1 to 25 of 105”
So then I jump from post to post again, by pressing the H key. In a Discourse forum there is know way of me jumping to posts or of knowing where about in a thread I am. After I have started reading a thread I have know way of jumping back in to a thread were i left off. I can’t find out if there is new posts. Lists of threads take a verrylong time to look through because I have to use the arrow keys to read down the hole page line by line and that takes a really long time. I hope this makes sense to you and sorry about my spelling. I am happy to answer questions.
A link that mite help is:
Accessibility Testing with the NVDA Screenreader YouTube
Thanks for reading Tapper.


Sure @jomaxro can you take as a to-do item to repro this with NVDA so we can fix?


Absolutely! Adding to my list. I’ll dig into this next week.


@sam Thanks! Yes, I’ll break out the document to particular issues, treating this as the master issue and linking back to here. I’ll also just note some immediate answers to your questions here, but then move this over to those separate issues.

re: “ESC” key for popup - this is about some of the helpful tutorial kinds of popups. It may be difficult to re-create with my user in (this was most visible for us for first-time users as soon as they enter a new instance), but I’ll see what I can figure out to make this more specific.

re: color contrast, sure I’ll post some screenshots there. Also, while there’s some small compromise between the aesthetics of the experience and making it accessible, this is quite minimal. I’m excited to talk this out with you! More concretely, in regards to:

Do we really need to touch that? That text is merely an embellishment, giving it great contrast risks people not being able to tell they can enter stuff in the text area.

Yes, the point of this work is that different users experience these features differently. :slight_smile: That’s where tools can help us with checking that when evaluating the tradeoffs between “how much contrast” when tuning RGBs :slight_smile:

Finally, the issue @tapper82 has described is a great explanation of “#31. Needs to be a way to browse among messages quickly” in the audit doc, so I’ll link that and spin it out as a separate issue. @tapper82 and @jomaxro I’ll mention you over there too so you can track any other progress and we can all figure this out!

Thanks all! Making separate issues now.


Okay, I’m done taking the items listed in the audit doc and adding them as separate topics. They’re all linked back here and someone has helpfully added an accessibility tag too!

Thanks for your help all, @sam hopefully that makes communicating and triaging and then finding some things we can try easier! Let me know what you think a good next step is, and I can check in more on this next week. Thank you! :slight_smile:


Hey @kevinrobinson,

Apologies, I got caught up in some other work. Can you confirm what I’m looking to test with NVDA? With all the split topics I’m unclear if the screen reader issue is resolved or not.


@jomaxro Sure!

I think message browsing is where @tapper82 was suggesting NVDA might be helpful: Accessibility: Need way to browse between messages quickly and @riking’s comments there and here: Accessibility: Focus management in topics seem like the trickiest ones to sort out, so where checking manually or tooling could help.

Also, someone helpfully tagged the various open accessibility threads here too: Topics tagged accessibility :heart:


Hi, it is so exciting to see that this is a priority for the Discourse team! Is there a recommended screen reader? I have a blind user that is interested in using our forum. Knowing the list of supported screen readers / technologies would be helpful to advise her on how to best access the forums.