Discourse with a screen reader

@MarcoZehe for our timeline control, I was a little on the fence on whether to go with the scrollbar role or the slider role. I decided on the scrollbar role because the control does scroll the page and it does sound like it fits the description given by the W3C:

A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area.

That said, it is a somewhat unique control we’ve built… it both scrolls the page and displays where you are within the current range of posts (so for example it will show you’re currently on post 6 of 12). It’s possible that there’s not a great way to mark it up for screen readers at all, and might be better off hidden… as normal page scrolling works as you’d expect without it. I’d like to give it a try and see what you think of it in action, and if it doesn’t work we can revert.

To answer your question @nolan, I’ve taken on the responsibility of organizing accessibility recommendations and getting our audit done, but most of my previous experience with accessibility comes from implementing specifications defined by others. We don’t have a dedicated expert working on accessibility full-time, as we’re still several orders of magnitude smaller than Slack… but this could be something we need to contract someone to work on in the meantime so we get it right and aren’t making things worse…

Thank you both for your replies, I really appreciate it!


Following up on the toolbar role, to clarify… are you saying the role isn’t worth it at all unless it follows this pattern as described the the W3C?

Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar.

If that’s the case then I won’t implement the role until we can get the focus and arrow key controls right.


Correct, if you use the role, you promise that you will also implement the design pattern. If you are not ready to provide the design pattern yet, don’t yet use the roller either.


Is this an appropriate place to report findings from my own accessibility audit for a hosted discourse instance, or should I start a new thread?


the third-party accessibility report and subsequent work I mentioned earlier aren’t being tracked publicly.

Any chance this decision could be revisited? Would be helpful to have some transparency around this that I could share with my clients.


Hey Aaron,

To ensure things aren’t lost, I’d recommend a new #ux topic (tagged #accessibility) for each finding in your own audit. If your findings are closely related it may make sense to use the same topic for each. Essentially we want things grouped into small chunks that can be tracked independently and marked “done” without needing to worry that we missed 1 item from a list of 53 in the OP.


OK, will do.
Posted the first one here: A11y: WAVE issues from homepage though seems like I don’t have permission to tag yet.


To elaborate a bit on this:

Using the role without implementing the pattern would be a bit like styling something to look like a button, then making it only respond if someone hovers over it and scrolls their mouse wheel. If I tab to or otherwise focus a toolbar, and it exposes all of its button separately or doesn’t respond to arrows, then it feels like that odd mouse wheel button might. You’d have to think before each and every interaction, and it claiming to behave in ways it doesn’.

Hope that clarifies things a bit. Knowing that something is a toolbar is only valuable if it behaves like a toolbar. Otherwise it’s distracting.


Aww, disappointing. Came here to ask what the status was on all these updates that seemed like they were in-flight when I posted this. I haven’t launched our community yet, but the old existing PHP forum is about to die so it’s now or never. Figured there’d have been some amazing changes by now.

But I couldn’t figure out how to reach my site’s admin area. I can certainly hit /admin, but the link to the site is still not accessible via keyboard in any way I found. That makes it a bit challenging when asking screen reader users to help me moderate.

Then I tried typing this reply 5 minutes ago, but somehow I clicked either an Edit or Quote button. It dumped me into what appeared to be an editable version of a previous message I sent. I tried hitting enter on a link labeled Cancel, but that didn’t work. Neither did reloading the page. Ultimately I sent the reply, then found and interacted with an inaccessible modal like the one I reported here initially to discard the message.

Has anything changed in this regard, or is there a public roadmap yet? As a screen reader user who has to interact with Discourse communities whether he wants to or not, I can make it work for me, but I don’t feel super comfortable asking a community of blind folks to use this–or, at least, asking them to build a community they’d enjoy on Discourse.



Unfortunately, that popped up a modal asking what you wanted to do with your draft (discard/save/cancel), and it seems modal focus capture is broken…


Discourse works for me but I’d definitely like to see some accessibility improvements. Its been a while since I used the admin UI or administrated a Discourse forum, but I’d expect a lot of progress to be made in 3 months.
I understand that ARIA can be challenging, but that in no way means that progress can’t be made. @nolan I’ve suffered that same problem before – it took me a while to figure out why the edit box hadn’t vanished when I clicked ‘Cancel’. I’d really love to use Discourse as a forum for my own community sometime in the future, but I may need to reconsider that if accessibility improvements aren’t made. And I’d hate to go back to PHP.
You guys practically have someone offering to help you with accessibility. Sorry if I sound impatient – I know this is tough and is hard for you guys. But both @nolan and myself are definitely willing to help, at any rate. I’d be happy to set up a Discourse test instance.


Sure, we appreciate the offer! If you see any easy changes, can you provide specifics? Many of the accessibility changes we are working on require restructuring the application, but we’re always game for any low hanging fruit.


A list, in no particular order with the exception of the first item:

  1. You have modals that don’t grab focus, which was what made me write this post in the first place. Anyone coming to this thread to give screen reader usage feedback is going to hit one of these, meaning that basic/intermediate screen reader users are filtered out. I haven’t hit this on my forum, thankfully, just here. Hopefully there’s some way I can turn these off, or at least, turn off whatever conditions would cause one to appear. The only way to interact with these is to wonder why none of your keyboard commands aren’t working, and to know enough about how web apps work to think of hunting for a modal. Then, once you’ve found it, you have to interact with it and navigate focus to the correct control. And even then it isn’t always reliable, as exhibited by my struggles replying to this topic.
  2. When I click a topic, keyboard focus doesn’t move automatically to the newest post. I’m not sure what’s supposed to happen here, so maybe there’s a different link I need to accomplish this? As such, keeping up with new posts is hard, and something I still have to do manually.
  3. There is no apparent way to reach my site administration area via the keyboard. I had to guess that /admin might work as a URL, and fortunately it did.
  4. ARIA landmarks in the forum posts would be useful. Essentially, make each post something like an <article/>, with <heading/> for the top controls and <footer/> for the bottom. This enables faster navigation by landmark, since there aren’t currently useful ways to move between posts quickly. I can sort of do that now via NVDA, but doing so drops me on the including the Like and other buttons. If the actual landmark elements won’t work, a role= attribute will.
  5. If I click the Topic actions button, there is no way to close the menu that appears via the keyboard.
  6. Your list widgets are kind of an accessibility disaster. I just tried moving a post with NVDA. Here’s how I did it:
  7. Clicked the Edit title/category button. I don’t remember exactly what this was called since, again, I can’t collapse the screen to get the button back.
  8. Found the category combo box.
  9. Activated it with space.
  10. Used NVDA object navigation to zoom into the selected combo box item, which was not at all intuitive.
  11. In that item, there is a list. I interact with it.
  12. In that list there is a search field, and another list. I interact with that other list.
  13. I then move through what appear to be a bunch of category descriptions, again with NVDA object navigation, until I find the one I want. I route the mouse to that.
  14. I click the mouse with NVDA.
  15. I suspect there’s another step where I have to find and click an unlabeled Save button, but I’m not sure and certainly won’t remember this the next time I have to do it. :frowning:
    As you might imagine, this is not intuitive, and something I only discovered because a) I’m probably an intermediate NVDA user b) I do web development among other things and c) I’ve kind of learned the ways in which Discourse does things.
  16. There are various unlabeled graphics which don’t identify as buttons, but which appear to do things. I think the Save buttons in the admin screens are an example. I’m sort of hesitant to randomly click unlabeled buttons on a live site relied on by users. That kind of thing is likely to bite me in a painful place someday. :slight_smile:

I’ll give things about a month, then I’ll slap PHPBB or something more accessible on a server and we’ll just go with that. Sorry, I’ve got a lot of folks not even giving the community a shot because of these issues, and given that the broken modal was quite literally the first speedbump I hit, I’m probably going to have to do what we as blind folks do far too often and pick the technically inferior but more accessible option. :frowning: Not trying to be grumpy, I just wish my choices for community weren’t a bunch of accessible options with smaller communities and less development, a great option with major accessibility issues, and mailing lists.

BTW, I’m a senior developer available for hire if you need help. To be frank, Discourse is eating enough of the internet that a bunch of us with disabilities have to grudgingly deal with accessibility issues like these when our well-meaning able-bodied colleagues set up a Discourse for their projects. And I get why they do, because I’d very much like to use it for our community, and you’ve created a product that is amazingly easy to administer. But if you don’t have an accessibility lead fixing current brokenness and ensuring that all new features are usable by people with disabilities, then let’s talk please, because you desperately need one. :slight_smile: The only reason I tried Discourse here is because I came away from this thread thinking that major accessibility changes were imminent. But in general, I actively discourage Discourse use whenever I have a say in it because of how hard it is to use with a screen reader, and because I don’t want to create another internet community where we as blind people can’t participate equally because of access issues. I’d love to change that, and to be a part of making that change happen. But if not me, then please bring someone on, because many of these issues have been around for years and haven’t changed to any significant degree.



Wow! Thank you for the detailed and thorough feedback!

I’m sorry, I don’t understand. I’m not aware of any modals that appear on visiting a topic? Are you referring to the editor / composer that one uses to write replies to topics, which I am typing in right now? Are you referring to the editor that appears after you press a reply button anywhere in the topic?

Since this is the first and most urgent issue, I’d like to understand it. Let’s maybe go step by step and start with the most important issue, since we’ve had blind users before and have acted on their feedback in the past – for example here:

and here

Perhaps we regressed recently? I want to understand what this “modal” is you are referring to.

(Also, did you try pressing ? to get the list of keyboard shortcuts? One thing I just noticed when investigating “how to get to admin area via keyboard” is that pressing = will get you to the hamburger menu but nothing in it is selected cc @sam – we should definitely fix that one.)


Hello, @ndarilek here. :slight_smile: Looks like I have another account here, didn’t realize I have two now. Maybe that’s why my email address didn’t work when I tried signing up in February. Here’s a quote from the first post about the modal I hit on signup. Note that there are a few issues listed in that post, some of which are likely duplicates of the ones I listed here. I think that part of my frustration is raising these again and again, and not knowing where to go to ensure that a) they’re rceived and b) that you’ve got the information you need. These modals in particular are hugely problematic because a) they’re hard to find for screen reader users and b) they block all input from reaching the page, so all of a sudden Discourse refuses to do anything when links/buttons are clicked. Anyhow, the quote–not sure of the quoting syntax:

• And not related to my site, but the modal signup experience here had some challenges. I tried signing up by email, but your instance rejected my .info email address which I’ve used for nearly 17 years and which worked fine on my own. I then signed up via Google, but the modal I was given on return posed some challenges:
◦ It didn’t grab keyboard focus, so I had to hunt it down and interact with it myself.
◦ While I was trying to do that, the infinitely scrolling topic list was adding new topics in and making it more difficult for focus to actually reach the dialog. I don’t remember how exactly I managed to move quicker than the topics appeared–haven’t had my coffee yet–but I’m here. :slight_smile:

Thanks, hope that helps.


OK, definitely hearing you, I’m still trying to figure out what this means:

Are you referring to the editor, the overlay pane that is used for editing in Discourse? I assume you must be? This is indeed not a modal, it is an overlay pane that stays with you, docked to the bottom of the browser, and “rides along” as you navigate through the Discourse site. You can collapse the editor to a single small summary line, or even expand the editor to fullscreen as desired, all the while you can keep reading topics in Discourse – even navigate to completely different topics – while you are composing your reply. This fits the theme of “encourage as much reading as possible” in Discourse, in that you can continue to read and navigate the site, your reading experience is not interrupted by the editor, as it is an overlay pane, docked to the bottom of the browser window.

The editor has two primary action buttons at the bottom left:

  • Reply – this closes the editor overlay pane and submits your reply to the topic (or to a different topic, if you have navigated away from the original topic)
  • Cancel – this closes the editor overlay pane and either saves the in-progress reply as a draft, or discards the draft

The editor also has a few other functional areas:

  • A “grab bar” along the top edge of the editor so you can control the overlay pane height, and adjust it up or down
  • An “editor type” button at the top left which lets you switch from a reply, to a personal message, to a new topic that references the original post
  • A “expand to fullscreen” glyph button at upper right
  • A “collapse” glyph button at upper right
  • A “hide preview” glyph button at bottom right. Pressing this button twice will show the preview again.

The editor should definitely grab focus when you press the reply button, e.g. “I am initiating a reply to this post.” It does in my testing, on both desktop, laptop, tablet, and phone. It switches to keyboard input and grabs focus when you press the reply button on the topic, or the reply button on any individual post.

Sorry if it takes a while to get to this work, we want to do it, it’s just that we have an overwhelming amount of work and a limited number of engineering hours, plus there’s an ongoing global pandemic that has had deleterious effects on many of us, and a number of the team have contracted COVID. I apologize; the best I can say is to pick out the most important issues and we’ll do the best we can to work on them first.

(Re-reading this, are you instead referring to the account signup process? It is possible we regressed there on accessibility as we did enhance the signup dialog in the 2.7 release?)


Aha! Finally something I can actually understand and repro. @sam I see what’s going on here… go into editor, type a bit of text in the editor so it wants to save a draft… press tab twice to be on the cancel button, then press enter. This dialog should now have focus, but does not – when I press tab I am on some other element. We should fix this and backport.


So my thoughts on this.

I’m on he fence really. I’m on Linux using Orca (which is the built in screenreadr) and it is seriously lacking, at least on my machine, for table navigation.

My main issues are two fold

First off. I don’t know where I am in a thread since there’s no easy way to keep track of individual posts. I can’t jump directly to the nexxt post in a thread, instead I need to scroll past all the add reply/bookmark/share a link/etc things to get to a new post

The layout is, for me at least, a mess of buttons and links everywhere. If things had headings, such as okay, heading 1 for the top bar, heading 2 for the first post in a topic, and heading 3 for each successive post I could live with that since it’d allow a screenreader user to quickly jump from one post to another without being caughtg up in all the clutter such as sharing links, liking posts and bookmarking.

Before I get told oh, do this, this, this, this and this settings wise. No. I shouldn’t have to go tweak a bunch of settings to make Discourse useable on my system.

What Discourse has done is great, really, on paper.

But why must I wade through a billion buttons just to get to a topic, or a thousand links? Okay. I’m exagerrating a bit, but hear me out.

This may be an opinion thing. but. I am used to things like pHP based forums that have headings for most things. So I’ll ask and would like to know if the lack of headings is a design choice or something that can be worked on to improve accessibility?

I’d suggest testing with Windows, Mac and Linux screenreaders, the built in ones for the latter two and NVDA (which can be found at NVaccess.org and Jaws (which you can get a demo version of for evaluating Discourse with for free because the software itself is paid and as much as a Mac), as well as Microsoft’s built in Narrator for Windows.

Phone navigation? I’ll leave that one be since I don’t have a phone with me currently to test. Not all screenreaders treat tables the same way. For example, on this topic, Orca (for me) doesn’t show the thread as a table, only the one that starts with ‘new activity’ in it and it skips completely over the topic and replies. If I go by heading, after going to the very start of a topic (which is a common navigation for screenreader users) it jumps down to the list of recommended topics after the last post, which is flagged as heading level 3.


Thanks for the report again @nolan… to address the first issue first, it looks like we’re not grabbing focus on most modals… this seems like a large regression we should fix as soon as possible (this week ideally)!

Definitely understand this, and while I can say we’re working on accessibility issues… we’re not going to have our current list completed within a month.


Yeah really sorry about the giant regression @nolan on dialogs! I didn’t understand how bad that was until I looked into it. We should have held up the release for it, it’s so bad!


Thank you! I installed NVDA today and am slowly getting a feel of the issues you are experiencing.

I completely understand the desire of getting Discourse working in a reasonable way using default bindings. I also understand much better the frustration around navigation.

I can see the phpBB tricks. NVDA is extremely limited there are not a lot of shortcuts to pick from.

The heading trick is unlikely to work on Discourse cause we allow users to enter custom headers in posts. For example:

heading 2

heading 3

heading 4

There is no “next article” button, best we have is “next region”, region support is somewhat flaky compared to JAWS. We already had an article element but NVDA did not respect it.

I made this PR to at least help people be a lot less lost when navigating through a topic:

I still feel the structure is not ideal. For example, the down button, gets trapped cause of our nested double-button in our post nav.

@eviltrout is investigating the focus issues with various dialogs, we are going to have to double test with NVDA to see if our fixes take.

We have quite extensive keyboard shortcuts if you quit browse mode, but I do get the reluctance of heading down that dark corner. The trouble is that once you are in “edit” mode you have to kick out of it to actually read the content.

For example:

j → computer says “article link visited”
down → computer says “link benno”
down → computer says “march 15”
down → computer starts reading post

After my fix there will be a major improvement

Instead of saying “article link visited” the computer will start saying “post #6 region article link visited”

Improvements here are going to be gradual, but we very much appreciate all the feedback. We are learning and will do our best to make Discourse more enjoyable to the blind community.

Modals feel like a general hornets nest. If we have a modal open and for any reason you manage to navigate back to the page you can get extremely confused. I do wonder if there is someway of signalling to NVDA - Hey NVDA … all these elements … no longer exist while the modal is open. We could pull them out of the DOM while modals are open but that may end up causing even more confusion.