Improve screen reader accessibility for website and coding examples

@frastlin

This issue was originally reported by @frastlin via react/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!

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.

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.

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:

the browser is supposed to know what that ARIA means and post the correct names, roles and states to the accessibility tree
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:

Firefox and NVDA on Windows
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)
Safari and VoiceOver on Mac
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.

@StommePoes

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 😄

Whoops 😦 Sorry. Accidental click!

@frastlin

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. :)

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.

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:

Mention there's a .kbd-navigation used in the markup, and corresponding JavaScript is in a script tag in the HTML tab?
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 😉)
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 :)

Data tables and complex tables (Tree Tables) have extremely spotty ARIA support and the patterns aren't quite firmed up. I think we're all still experimenting. The best advice now is keep it simple! Keep cell content homogenous and single-interaction. This area of research is still rife with possibilities and solutions.

@roblevintennis

We have to be very, very careful when deciding to remove focus styles. I get what @roblevintennis is saying in that "well people will do it" but while people will hang themselves we have a responsibility if we're the ones providing the rope.

We need to test, test, and test some more anything that bakes-in removing focus styles because some JavaScript thinks it could determine an input method: speech recognition for example is a bit notorious in sometimes triggering some events (blur) while not triggering others (dictating into a text input may not trigger an onChange).

Users with touchscreen laptops with mobility issues switch around between pens, fingers, mice and keyboard and there are some things out there that act like keyboards but not always (for example Switch Control has its own focus thing going on where groups of focusables can themselves be considered "focussed" by the software... though so far as I know I believe it provides its own focus styles. One of these days I really need to dedicate myself to testing various CSS/JS focus-style wrangling with a couple of switch control programs).

I think whatever discussion here happens, for now it's probably not a good idea to have example code removing focus outlines. It could instead implement a nice/pretty focus style, which a) would remind people focus styles are a thing and b) remind people they don't always have to look like browser defaults, and move discussion about allowing anything baked-in to remove focus styles to a dedicated discussion.

As a note, from a Windows High Contrast fan: if you remove the outline property and do something like change a background colour, keep in an outline but use "transparent" as the colour: people who set their own colours of texts and backgrounds to ensure a super high contrast will not see your own colours, as they are overriding with theirs and at least specifically Windows High Contrast doesn't have the full range of styling that CSS has. Just always keep a outline: 1px dotted transparent; somewhere.

@StommePoes

@StommePoes the outline: 1px dotted transparent; approach feels like a great way to preserve for folks setting their own colors. Love that!

I think we're talking about the same thing, but the unadulterated example (and mine) are BOTH removing with: outline: none and then using the background color on focus. I was sort of just preserving what they had, and looking at other areas of the code to add some of my own ideas to @frastlin initial example.

I agree with your sentiment of avoiding outline: none altogether, and the other points you've made regarding Switch Controls, etc. Unfortunately, it seems when I added this my pen got forked. The updated is at https://codepen.io/roblevin/pen/PMjNwo?editors=0010

Loving all the learning opportunities on this issue thread!

@flarnie

Hey all! I'm new to the thread, but I see there has been some awesome collaboration here that I'd like to help along! As a Developer Advocate for an accessibility testing company, I cannot stress enough the impact that could be made in the industry by introducing even basic accessibility concepts into the minds of new developers from the very beginning. This is right up my alley :)

I think the high-level topic of enhancing the accessibility of the documentation and code samples overall is a great goal, albeit pretty wide-ranging for a single issue thread to cover completely. I'd be happy to offer to start (and help tackle) a focused, crowd-sourced "task list" that can be approached in a modular, agile, and collaborative fashion (i.e. separate issues and small, clean PRs). @flarnie + @bvaughn, is that something either of you would like to be a part of?

First, though, I feel like this thread (@frastlin and @roblevintennis especially) made some really good progress towards integrating some accessibility improvements into the Tic Tac Toe starter project, and I'd hate for that to not bear any fruit! I'd be very happy to create a PR to capture (and further refine) the insights from this thread in the form of (1) code sample tweaks and (2) updates to the documentation language. Does anyone feel like that's premature, or that it needs to be revisited now that a bit of time has passed?

Yes, from a screen reader perspective:
https://codepen.io/roblevin/pen/PMjNwo?editors=0010
looks great and should be the example used in the tutorial.
CSS is not my strength, so if someone can do something to make the high contrast work while still keeping the look of the current game as much as possible, I think that's all that is needed before a PR will be ready.

Okay, I've gone ahead and normalized the look-and-feel of that code sample (in a forked Pen), and did some very minor tweaks, including:

Changed the CSS hidden class to sr-only, since it's not truly hidden, just visually hidden.
Made the <caption> sr-only to match the appearance of the existing code sample
Changed the text of the empty squares from "Empty square" to just "Empty" to reduce noise (hopefully not by too much).

Here's the updated code sample: https://codepen.io/jasonwebb/pen/eYNdbpp?editors=0101

I'm not 100% sure where the conversation landed regarding focus styling. In my personal experience working at an accessibility consulting company, I see people get this wrong far more often than they get it right. Given that this is a starter tutorial that is meant to set a good example of best practices for novice developers, I feel like relying on native focus styles and behaviors as much as possible would be best.

When :focus-visible is more widely supported we might want to include it in this example, but until then we'd have to add a polyfill which just introduces (1) complexity and (2) external dependencies (possibly). I would vote for us trying to keep the sample as simple and focused as possible so that beginners don't have to learn React AND intermediate/advanced focus styling.

If this code sample is still looking good to folks, I can start looking at the documentation text and developing code sample replacements for the individual "steps" that are there now. Before going too much further down that route, though, I'd like to touch base with the maintainer(s) of this repo to see if this work is in alignment with their vision so I don't end up creating a dud of a PR :D

@jasonwebb

Hi @jasonwebb I appreciate you jumping in and I'm glad you're continuing to take the pen further with your fork. I saw your earlier comment too, but I've been totally swamped.

I did just have a look at the linked pen and (maybe this was happening on mine too?) but when I first landed on that page, and then clicked the top left most square, the whole grid re-rendered and I lost my 'X'. Hopefully that repro is clear enough. Ironically, it's a bug for sighted or mouse clicking users for this case.

It's interesting, since having done the referenced pen (probably a good several months back), I've implemented a data grid basically complying with this one: https://www.w3.org/TR/wai-aria-practices/examples/grid/dataGrids.html. I don't yet have a public link unfortunately, but it's aria based not table so perhaps it will suffer from the limited aria support we currently have but getting better.

The overarching navigation rules they set out were basically that you: first tab into the grid, and then, switch to using arrow and home/end keys to navigate. It took quite a bit of doing to pull off, but I'm using it in a product my current employer is working on (unreleased).

So now I'm wondering what the exact rules are for when you're supposed to switch from using tabs to using arrow keys once you're "inside" a grid and if that is considered totally different from what's being done here (a literal <table> element being used to navigate the matrix of a game.

I feel you on wanting to get some feedback from the maintainers that a pen rather a PR, would be utilized in their docs if done correctly—you don't want to spin your wheels. I was mainly doing these pens as an exercise and since I was having the opportunity to learn some real a11y tips from @frastlin; and also because I do think we should be perpetuating moving towards a11y not away from it (even though I admit I need to get a lot better at it myself!).

But, yes, I absolutely agree that something that actually works in terms of being accessible would make an ideal example for a framework as popular and prolific as React. I'm sure the maintainers want to do what's best and must have a ton on their plates, but, we'll just have to see what they decide to do here.

I just learned Svelte, and was intrigued that the author has elected to bake in a sort of eslint / a11y warning mechanism if you don't do something correct—and that's a definite competitor for React however small its market share is at the moment—maybe such healthy competition will also help incentivize being fully a11y-friendly in the documentation ;-) 🤞

@frastlin

Re: CodePen mouse click refresh glitch
I'm willing to bet that the mouse click glitch you're seeing is a quirk of the CodePen Editor UI. CodePen will recompile and reload the JavaScript when you first load the editor (look for the status messages at the bottom status bar, to the left of the "Delete" and "Add to Collection" buttons). Try it in the Debug view, or just wait for the Editor to fully load, and see if its still happening.

Re: using the ARIA grid pattern
In my view, an ARIA grid for such a simple and beginner-oriented sample would not be the most appropriate here for either the readers or the imaginary end users. I feel like it goes against perhaps the most important rule of ARIA - No ARIA is better than Bad ARIA.

First, consider the audience for this code sample - beginner developers. Having them learn something as advanced as nuanced as the difference between native <table>s and ARIA grids could do more harm than good, and plant an idea in their minds that accessibility is harder than just using native, semantic markup. As you say, "[i]t took quite a bit of doing to pull off" - maybe not the best experience for first-time readers, who may also be very new to web development in general!

Second, consider the imaginary end users - my understanding is that ARIA grids are not encountered nearly as often as <table>s are in the real world, so many screen reader users (especially novice or part-time users) may find them to be unintuitive outside of very specific use cases compared to <table>s. Also think about people who only use their keyboard, but have varying degrees of (including full) vision. An ARIA grid has a single tab stop, whereas native tables let their contents dictate the tab stops, which can feel pretty strange without additional visible instructions. A table with individually focused contents, however, would not need any additional instructions (IMHO). I'm open to being wrong on this, though, if anyone has another perspective!

It sounds like this has been discussed quite a bit already in this thread and its predecessor ([1], [2]), so I suggest we pick the table approach and move forward.

Next steps
Just to help clarify my high-level thinking/strategy, my hope is that we can open up a PR that creates the most amount of benefit with the least amount of deltas. What you and @frastlin have done so far has been spot on as far as prototyping, so now the next step is to integrate it (which I'm happy to help with :)).

With that goal in mind, here are the major steps I'm thinking about to get this code sample integrated into the documentation website:

Create an updated version of the Final Result code sample found in the Wrapping Up section. This is what we've been doing in this thread so far.
Create a series of replacement code samples for the individual steps that lead up to that final result. For example, there are code samples under Inspecting the Starter Code (for the "Starter Code"), and Passing Data Through Props (near the end, with the link text "View the full code at this point").
Adjust the text of the tutorial to accurately reflect any significant changes in the code samples. I expect this to be pretty minimal, since the focus of the tutorial is really on the logic and React aspects, which I'm pretty sure will be unchanged.
Open a PR with the text changes and links to the updated CodePen samples. Ideally these CodePen samples would be transferred / forked to an "official" account of the React team upon approval by the reviewer(s).

As @bvaughn said above, it'd be good to reach out to the maintainers to make sure we're in alignment before doing steps 2, 3, and 4. If we don't hear from them on this thread in the next couple days or so I'll form a search party :D

Please let me know if any of this could be explained better, or if you have any other questions!

@jasonwebb

A grid component would be the best UX for this, but it's so difficult to make a quality aria grid, it's not worth the trouble.
In fact, it's so difficult to make an aria grid using React, that it's never been done before to my knowledge, and I've been looking very hard for a good solid example.
@jasonwebb your plan looks great.

@jasonwebb

I'm good with above @jasonwebb 👍

Yeah, I digressed regarding the aria grid (wish I could somehow conveniently show what I have (it's behind a VPN atm). But I totally agree that would add too much complexity for the simple tic tac toe example (it is quite complicated to pull off at least the way I went about it).

So I agree and appreciate you're taking the ball on it Jason!

@jasonwebb

A grid component would be the best UX for this, but it's so difficult to make a quality aria grid, it's not worth the trouble.
In fact, it's so difficult to make an aria grid using React, that it's never been done before to my knowledge, and I've been looking very hard for a good solid example.
@jasonwebb your plan looks great.

Sorry, to belabor the web-aria data grid thing, but, I'm curious if the web aria data grid examples work well to your mind, in terms of a baseline for what could be done there: https://www.w3.org/TR/wai-aria-practices/examples/grid/dataGrids.html @jasonwebb? I presume there's still the issue of ubiquitous support, but I'm wondering if the support for such an implementation is at least decent across assistive technologies?

The WAI-ARIA Authoring Practices guide is a great resource, and yes, that is a nice starting point when building out ARIA grids. However, from an education standpoint, I feel that the additional complexity of the ARIA grid pattern in terms of interactions, JavaScript, and markup is not the best fit for the very first tutorial that new React developers (who may also be new developers in general) are exposed to.

We'd have to introduce relatively difficult concepts like the roving tabindex, and potentially touch on basic screen reader usage so that the reader can actually experience and verify that their copy is fully working as expected. All things considered, it feels like using an ARIA grid in this scenario would require adding complexity to the code and the narrative documentation, which takes away some of the focus on the actual core intent - the React aspects. I'm also concerned about the possibility of planting an idea in the reader's mind that accessibility is complicated (perhaps more complicated than learning React), when it really doesn't need to be.

When it comes to screen reader support, I agree with both jessebeach an StommePoes - ARIA grid support has been improving, but native <table>s are still way better. Again, check out the #1 rule of ARIA usage: No ARIA is better than Bad ARIA.

Grids are becoming expected by screen reader users, as google sheets, gmail, and other major applications use them. If it was as easy to make a grid as it is to make a table, then I would recommend to make a grid. But it's over 500 lines of code to make an aria grid, and only 20 or so lines to make a table. If we were using an existing grid component in React with those 500 lines already done, then I would say go ahead and use it, but newbies don't know about custom components at this point. So use a table element please.

Building Your Own Hooks page translation (reactjs#78)

I'm waiting for the day that screen readers are no longer required. They are expensive and a pain to learn even if you are a sighted user! I dream of the day that voice recognition/synthesis can be used to make a "hands free" UI that would benefit all users including the blind. I realize there are security concerns with a UI that "listens too much" but our iphones do that :-) (my apologies, I just had to interject)

Sync original (reactjs#78)

Navigation Menu

Repository navigation

Improve screen reader accessibility for website and coding examples #78

15 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Improve screen reader accessibility for website and coding examples #78

Description

Activity

jenshedqvist commented on Oct 10, 2017

bvaughn commented on Oct 10, 2017

StommePoes commented on Oct 11, 2017

bvaughn commented on Oct 11, 2017

bvaughn commented on Oct 11, 2017

flarnie commented on Oct 11, 2017

bvaughn commented on Oct 11, 2017

roblevintennis commented on Jul 26, 2019

jessebeach commented on Jul 27, 2019

15 remaining items

StommePoes commented on Jul 31, 2019

roblevintennis commented on Jul 31, 2019

jasonwebb commented on Feb 10, 2020

frastlin commented on Feb 10, 2020

jasonwebb commented on Feb 20, 2020

roblevintennis commented on Feb 21, 2020

jasonwebb commented on Feb 24, 2020

frastlin commented on Feb 24, 2020

roblevintennis commented on Feb 24, 2020

roblevintennis commented on Feb 29, 2020

jasonwebb commented on Feb 29, 2020

frastlin commented on Feb 29, 2020

horowitza commented on Jul 8, 2020

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions