Improve screen reader accessibility for website and coding examples

[bvaughn]

This issue was originally reported by @frastlin via facebook/react/issues/9549

That issue has a lot of discussion worth reading. Although some of the specific issues mentioned in that thread have since been addressed, I'm moving the issue here to continue the discussion!

[jenshedqvist]

I think maybe the biggest challenge is that the tools people with special needs use (such as screen readers) will always lagg behind the a11y specs. I've recently followed the latest WAI/WCAG/Aria specs but got the feedback that "Yes that's how it is supposed to work, but it doesn't yet. So it is of no help for me. Standards aren't reality". So if tables are a must have and aria isn't enough alltough the specs says so, then tables it will have to be.

[bvaughn]

So if tables are a must have and aria isn't enough alltough the specs says so, then tables it will have to be.

I'd like to learn more to confirm that ARIA isn't enough. I'm not super knowledgeable in this area. Do you have references?

I also left a comment on the previous issue.

[StommePoes]

If you create a "table" out of something else + ARIA, yeah I would advise testing in a few screen reader + browser combos. Two things are supposed to happen when you ARIA something:

1. the browser is supposed to know what that ARIA means and post the correct names, roles and states to the accessibility tree
2. the assistive technology (AT) is supposed to rely on that tree to know what's going on. AT is slowly moving in that direction, esp as newer browsers like Edge disallow DOM-dumpster-diving (accessing the DOM directly in the way that JAWS and virtual-buffered SRs traditionally have).

So the browser needs to output the right tree and the AT needs to understand that tree.

When testing if some general thing works as we think it should, these tend to be my recommended testing combos:

1. Firefox and NVDA on Windows
2. IE and JAWS (if you want Edge and JAWS, know this is isn't complete and you have to enable Edge-use manually in JAWS now; I believe this is also only in the latest (18) version, older versions don't do squat)
3. Safari and VoiceOver on Mac
4. Safari and VoiceOver on iOS (I add this one because it seems the iOS VO devs get more support or something so often VO on iPhone works way better than VO on desktop). For now avoid testing Firefox with VO on Apple products, Mozilla says their browser doesn't have enough access to things properly yet. Chrome is "okay" but a second choice.

If you're making a product for enterprise, people tend to just do the first two. Testing every combo of every thing isn't what anyone wants to do, but for seeing if a feature has enough support to be a thing, this is my personal bare-minimum list. Also we assume the tester is familiar with the ways one interacts with a table with a screen reader-- tables have table navigation and some other neat features that are a bit special to tables.

For an example where ARIA isn't enough: back in March I saw a presentation by an education company where they have eText in a special eText reader and they gave a tabindex=-1 to an error message on a form and moved .focus() there. I asked why that wasn't just an alert role (those are read out when they appear without moving the user's focus). They said the clients running most of their education software didn't have robust enough ARIA support. Dragon (speech rec) seems to have hit and miss ARIA support, at least with my version (13).

Some things were in the authoring guidelines 1.0 which have been dropped until the ARIAWG can get back to it for 1.1, like drag and drop. There's a bunch of aria roles and states for drag and drop but whether they do anything is very hit or miss, and you tend to need to hack around to get things working since browsers and AT seem to have sorta half implemented it.

Some parts are newer, like aria-current. Aria-current got JAWS support pretty quickly but for non-bleeding-edge users (something that costs and arm and a leg is likely to have users on non-latest versions), hidden text stating a particular menu item represents the current page may still be needed because support is still catching up.

Nothing wild, but it's a good idea to test anything if you haven't seen it already working kinda everywhere already.

[bvaughn]

Thanks for the added context and info, @StommePoes

It looks like the testing combos you pointed out are also mentioned in the React docs under Accessibility - Screen Readers! I hadn't even noticed that before.

cc my teammate @flarnie who did some a11y auditing for the initial launch of the site 😄

[bvaughn]

Whoops 😦 Sorry. Accidental click!

[flarnie]

Thanks so much @frastlin for opening the original issue, and @StommePoes, @jenshedqvist for the helpful info and discussion.

It sounds like the lack of accessibility in our examples was really frustrating and could have spread bad patterns - I apologize for that. Glad to hear the concerns everyone brought up, and we'll work on making things better.

• The original issue points out a11y issues with FixedDataTable; I think you are right that this table component is not very accessible, and I just pinged the guardians of Open Source at Facebook to archive that project. Internally we have been moving away from FixedDataTable, and I believe accessibility is one of the reasons.
• Sounds like the issue with buttons lacking labels in the tutorial has been fixed; we're happy to get other reports if any similar problems remain with current examples.
• The accessibility team at Facebook is actively working on developing patterns and best practices for this, such as developing the Logical Grid Pattern that @jessebeach blogged about recently. cc @tatermelon in case you have ideas to add here. They also added the 'Accessibility' page in our docs, which covers some of the ideas folks mentioned in this issue.

Let's discuss any remaining action items to improve the examples and docs. Really awesome that we can work together on improving accessibility. :)

[bvaughn]

Adding to what Flarnie said- we'll also be happy to review PRs that improve accessibility (if you have any interest in contributing them).

Feel free to ping us ahead of time to discuss any large changes that you might be considering if you think they may be controversial.

[roblevintennis]

Firstly, with all due respect, I'd like to thank everyone here that's created such a wonderful framework in React! The community is so thankful for all your efforts!

It sounds like there's a lot more work to do here, and much of it is educational for me and I honestly do not feel qualified to provide feedback or help on this bug. I'd just add, that as a likely typical reader of the documentation, I saw no mention of the .kbd-navigation bit and didn't notice it until after having wondered if I could navigate with tabs (much much after I'd coded up like 3-4 tic tac toe codepens in trying to cement my React learnings, and then, this week, in my Accessibility studies of late, realized, "hrm, oh oh, I forgot to make that game, if not screen reader accessible, at least keyboard accessible.").

I'm referring to the current final result at:
https://codepen.io/gaearon/pen/gWWZgR

My whole point in saying this, is I think for the interim (while the more detailed issues with various screen readers and this bug are getting resolved), could you not at least:

1. Mention there's a .kbd-navigation used in the markup, and corresponding JavaScript is in a script tag in the HTML tab?
2. Or move that in to the JavaScript tab? It sort of feels like either an afterthought, or it's purposely being avoided (I'm not saying that's the intent! But, just from a UX standpoint it feels this way 😉)
3. Can we at least make mention of it somewhere in the tutorial? Even if it's to say, "hey, we haven't completely solved accessibility for this example but are working on it. In the meantime, we DO offer keyboard accessibility and you can have a look at the .kbd-navigation used etc. etc."

I think this would be helpful and an awesome step in the right direction so other developers like myself don't completely forget about this important part of front end development as they learn this wonderful React framework you've worked so hard on! Thanks :)