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

[jessebeach]

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.

[frastlin]

OK, so simple fix for this:

1. put the button rows into a table. Every row should be a row in a normal table, just without headers. It's much prefered if the table element is used and css is used to style the table to look good. If that is completely impossible, then there is the role="table", but the native table would be much better.
2. Make the blank buttons say "Empty Square" or have a graphic of an empty square, then have the alt text say "empty square. ("empty" sounds fine as well). Currently the buttons are just blank which looks like a bug.
3. The div that shows: "Next player: X" should be an aria live region with atomic="true". This will give the player some feedback when they click the cell.

I'll try and do a PR now.

[roblevintennis]

@frastlin I appreciate this and will keep an eye on github notifications. I think I could probably attempt to code up your specification but with your knowledge I think yours will be extremely helpful.

Re

Data tables and complex tables (Tree Tables) have extremely spotty ARIA support

I absolutely appreciate how complicated this could all get for certain tables and I read the logical grid article which was quite educational. However, in the interim we're talking about a simple game of tic tac toe, and, other use cases might be simple enough to be solved with today's tech. I see it oversimplified as:

1. the simple low hanging fruit cases
2. the complex data grid cases with a plethora of crazy controls, deletable cells, yada yada.

Obviously, both cases must get figured out, but I'm wondering if the simpler ones aren't already solvable? Hence I'm looking forward to seeing what following @frastlin spec is (even if it's using tables which some folks might be against, but if it has better screen reader support and is viable in the interim maybe it's fine?)

@jessebeach I'm really looking forward to seeing what your team comes up with though. It sounds like a lot of research and I absolutely appreciate that and the article which was very informative.

Re

Every row should be a row in a normal table

This is because it's better supported today by assistive technology correct?

@frastlin thanks for bringing all this up in the first place and I look forward to seeing your demo if you find time!

[frastlin]

Here is my version of the code. What are your thoughts? Most of the changes are in the Board render function. There are two render functions: The first uses the table element, and the second uses aria.

There is a problem with both examples though: Since this is a game, it is a non semantic interface, which means that it does not follow proper HTML rules. For example, It is not ever correct to have a table without a header in a semantic interface. But this is a game, so it should have good UX, above being semantically correct. I'm worried though that new developers, who are the ones that will be reading this tutorial, are not going to understand the difference between semantic and non semantic interfaces. 99% of interfaces on the web are semantic, and should follow proper HTML practice, but this is part of that 1% that shouldn't. React has already encouraged the use of divs for everything, and this has really broken many websites, because divs communicate nothing to the screen reader, and aria is way to advanced for the overwhelming majority of web developers (mostly because they don't use a screen reader). So the react tutorials and examples should all follow WCAG2.1 AAA, so developers know what is good practice. Because most developers learn good practice from tutorials and examples like this. Because no one should use aria unless it's a last resort, or they have a non semantic interface (like this one), I am very hesitant to recommend the aria example, even though it would be a good place for aria.

[roblevintennis]

@frastlin Thank you so much for coding this up!

So I see renderDiv is just there for aria based example. Thank you!

While I think the example should obviously address those users of assistive technology, I think those that do not should still be able to enjoy the game, and so I've forked your pen and taken the liberty to resize the game and strategically position the Empty Square. I used a sibling span to the square buttons (probably I should have used a better, but that could be easily refactored) that's fixed in latest version: https://codepen.io/roblevin/pen/WVoyPm?editors=0010

Now I'm left wondering:

1. Does the now meaningless <button> when no props.value violate and confuse screen readers? I'm assuming the answer is "yes" and so my implementation is yet ready.
2. Is there a mechanism that could be used to dynamically disallow the button when props.value is falsy?

For the later, could we not just toggle a button's attribute of aria-hidden="true" or aria-hidden="false" to achieve that more satisfactorily?

[roblevintennis]

Update: I've used a <label> and I'm toggling aria-hidden on the button. My understanding is that as long as ancestors don't have aria-hidden set to true, you can use false value reliably. Is that in fact true?

Same pen: https://codepen.io/roblevin/pen/WVoyPm?editors=0010

[frastlin]

No, this example doesn't work, the empty square doesn't take the onclick event, and I think the code is way too detailed. It's also using more aria, which should really be avoided at all cost. Use CSS rather than HTML to make it look good. If the problem is that you want the squares to be blank, go ahead and use one of the tricks to make text hidden to sighted users.

.hidden 
{position:absolute;
left:-10000px;
top:auto;
width:1px;
height:1px;
overflow:hidden;}

[frastlin]

I just updated my code pen with your CSS and with making the class hidden when there is no value in the button. I'm not sure this hidden class is working, my screen reader says it is still 21PT. I'll try messing around, but me using CSS is like a sighted person using Aria, very very very difficult! If there is something you can't do in CSS, let me know and I'll try to fix it in the HTML. The only CSS a screen reader user sees is shown in the above hidden link. Other than that, you can do anything in CSS for sighted users and the screen reader user won't care. It also decreases the complexity required in the tutorial code majorly.

[roblevintennis]

That's absolutely a fair analogy and I'm still very much learning on this front! Unfortunately, all the squares are now pushed off the window for me. However...

It occurs to me that I overlooked a version that's much closer to your original example. I do not need to use a sibling at all for "empty info" since I believe I'm allowed to use a span or anything that qualifies as phrasing content inside a button: https://www.w3.org/TR/html50/dom.html#phrasing-content-1

Given I was able to put the "Empty Square" text in <span> I was able to use the visually hidden to hide that (but not the button itself as per your last version). The only other thing I added was making it a fixed-layout table which as I understand it, is generally better performing in terms of reflows and rendering, and given it's a game that seems fine.

and I think the code is way too detailed

Right, I think the code is back to being simple and without the extra aria too. Here's the forked pen with said improvements: https://codepen.io/roblevin/pen/GVNYed?editors=0100

What do you think of it?

Update: I just tried the game with Apple VoiceOver. I cheated to get in to the proper content tab, but otherwise forced myself to use the screen-reader and was able to play the game. I figure codepen is an artificial environment and can imagine a page without such hurdles.

By the way, I see what you mean about the line you added for status updates:

<div aria-live="polite" aria-atomic={true}>{status}</div>

It's really helpful to hear those updates.

I'm not sure why it's saying column 1 of 4. That's an extra and confusing. Semantically, it should be column 1 of 3. Is that a common issue? Or is there something in the code I'm overlooking?

[frastlin]

This looks good to me. Why not just place the x and o in the span and change the class? Whatever is easier to understand for newbies.

Also, what is:

.kbd-navigation JavaScript in HTML tab to see // how keyboard navigation and mouse navigation are being toggled // to preserve use by assistive technologies

? I didn't understand this, what is it for? Screen reader users don't need it, semantic buttons and table elements already provide perfect tabindex, click, and arrow key functionality. If there is another type of assistive technology you're targeting, that's fine, but I've never seen it before.

[frastlin]

Re: VO: I have no idea, NVDA on Windows says table with 3 columns and 3 rows. This is a nonsemantic interface, so it could be confusing VO (which is not as robust as NVDA or Jaws). But a user who knows how to navigate tables using the screen reader will be able to view the board using the table navigation commands (NVDA it's ctrl+alt+arrow keys), and this clearly shows a 3 by 3 grid.

[frastlin]

I think we can reduce the number of lines of the square function by making it:

function Square(props) {
    const emptyInfo = <span className="hidden">Empty Square</span>

    return (
    <div className="square-container">
      <button className="square" onClick={props.onClick}>
        {props.value || emptyInfo}
      </button>
    </div>
    );
}

I don't see any need for the function.

[roblevintennis]

Regarding the comment, yes, that was totally confusing, my bad. I've changed it to hopefully make more clear the intent.

It now reads:

// Please see the .kbd-navigation JavaScript in this pen's HTML tab
// to see how the keyboard navigation visual affordance is being toggled

The point of this, is to call out to readers of the example, that keyboard navigation styles are being toggled in the HTML tab of the Codepen pen. Many folks trying to learn React, will assume there's some placeholder HTML only used for the React sample app to hook in to with something like ReactDOM.render et al, and will very likely never even open that tab.

The global JavaScript I'm referring to essentially toggles between mouse and keyboard with dynamic classes .mouse-navigation and .kbd-navigation, so I think it's important for folks to go see what's happening there—especially since the documentation's tutorial makes no mention of it. If that were to change, I think the comment (which is really insufficient but at least "something") could be removed.

Also, that code seems way too global to me, but I haven't had time to consider an alternative properly. I think we could bring it closer to the game itself so it's less global.

Since we now have proper navigation for screen readers through the table-based approach, I suppose the only benefit the .kbd-navigation code is adding is the highlighting of squares via:

.kbd-navigation .square:focus {
  background: #ddd;
}

But we do need this...

In my reading about accessibility, there is the case made for someone who needs this sort of affordance if say they have tendonitis in the wrist or similar and cannot use a mouse but prefer keyboard navigation. They will be helped by the visual affordance the grey background offers as they navigate into and out of the squares.

That said, I'd be really excited if a developer could somehow just opt in for this sort of thing without having to write messy global event toggling handlers to do so. I could see this as either a 3rd party library, higher order function or component, or something to that affect. The current solution doesn't really scale for more complicated pages with nested components that may have naming or intent collisions e.g. if I elected to implement some sort of keyboard listening code but deeper within the component and/or DOM hierarchy (not an issue for this simple game of course). I would then have to debug to learn there was code doing toggling off the top level of the DOM.

Re the span thing, no, I cannot just add the 'X' and 'O' to the span. It is being used for the 'Empty Square' message and needs to be there for sighted users as we want that visually removed (but we do not want the 'X' and 'O' visually removed which is what would happen if they were placed in the span itself).

I agree about the extra function, it was left over from my earlier hacking. I've cleaned that up just now.

Re: VO: I have no idea, NVDA on Windows says table with 3 columns and 3 rows.

That's great to hear!

This is a nonsemantic interface, so it could be confusing VO (which is not as robust as NVDA or Jaws). But a user who knows how to navigate tables using the screen reader will be able to view the board using the table navigation commands (NVDA it's ctrl+alt+arrow keys), and this clearly shows a 3 by 3 grid.

This is all very educational to me as I try to level up my understanding of accessibility @frastlin so thank you for your invaluable feedback and guidance!

[frastlin]

I thought that browsers provided highlighting by default for what element is focused? Another option is to add an onFocus function to the button element that highlights the square when it is focused and removes the highlight when it is not focused. This would remove that global code.

[roblevintennis]

Right, the browser generally provides an "outline ring", and the original tutorial's pen (and our refactored ones as well) have:

.square:focus {
  outline: none;
}

.kbd-navigation .square:focus {
  background: #ddd;
}

Many folks don't like the aesthetics of this "outline ring" and will turn it off as such. Many times without even providing an alternative which is the worst case. At least here, they've elected to, essentially, override it with the grey background which is probably a good thing in terms of maintaining an affordance of some kind (disclaimer: I may be overlooking some detail on what's considered a good focus affordance; but it seems reasonable to me).

Regarding attaching an onFocus handler and I suppose an onBlur for exiting, yes, that and many other solutions would work and be scoped much closer to the "game" portion of the DOM tree.

Ideally, all this would be added in the React code itself. In terms of the new learner's perception, as it is currently coded (within the HTML tab of the codepen pen, and as a global), it comes off as an afterthought and could be interpreted that it was too hard for the original developers to incorporate into the React code itself—probably not the ideal message to send to the React learning community.

But above is just my opinion I guess. What do you think?

[frastlin]

I think that rather than handling this styling in React, it would be better to handle it in CSS, as it is styling. :focus should do this, but I can't test it to see how it works. I believe the code would be:

.hidden:focus { background: #ddd; }

Then we get this behavior how we want it, if I'm understanding correctly. I think the amount of code should stay as little as possible in the tutorial.

[StommePoes]

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.

[roblevintennis]

@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!

[jasonwebb]

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?

[frastlin]

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.

[jasonwebb]

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

[roblevintennis]

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 ;-) 🤞

[jasonwebb]

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:

1. 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.
2. 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").
3. 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.
4. 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!

[frastlin]

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.

[roblevintennis]

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!

[roblevintennis]

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?

[jasonwebb]

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.

[frastlin]

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.

[horowitza]

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)