New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve screen reader accessibility for website and coding examples #78
Comments
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. |
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:
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:
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. |
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! |
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.
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 I'm referring to the current final result at: 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:
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. |
OK, so simple fix for this:
I'll try and do a PR now. |
@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
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:
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
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! |
Here is my version of the code. There is a problem with both examples though: |
@frastlin Thank you so much for coding this up! So I see 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. Now I'm left wondering:
For the later, could we not just toggle a button's attribute of |
Update: I've used a Same pen: https://codepen.io/roblevin/pen/WVoyPm?editors=0010 |
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.
|
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. |
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 Given I was able to put the "Empty Square" text in
Right, I think the code is back to being simple and without the extra aria too. Here's the forked pen with said improvements: 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 <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? |
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 ? 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. |
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). |
I think we can reduce the number of lines of the square function by making it:
I don't see any need for the function. |
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 The global JavaScript I'm referring to essentially toggles between mouse and keyboard with dynamic classes 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 .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.
That's great to hear!
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! |
I thought that browsers provided highlighting by default for what element is focused? |
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 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? |
I think that rather than handling this styling in React, it would be better to handle it in CSS, as it is styling. .hidden:focus { 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. |
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 |
@StommePoes the I think we're talking about the same thing, but the unadulterated example (and mine) are BOTH removing with: I agree with your sentiment of avoiding Loving all the learning opportunities on this issue thread! |
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: |
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:
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 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 |
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 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 ;-) 🤞 |
Re: CodePen mouse click refresh glitch Re: using the ARIA grid pattern First, consider the audience for this code sample - beginner developers. Having them learn something as advanced as nuanced as the difference between native Second, consider the imaginary end users - my understanding is that ARIA grids are not encountered nearly as often as 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 With that goal in mind, here are the major steps I'm thinking about to get this code sample integrated into the documentation website:
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! |
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. |
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! |
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 |
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 * Improve translation Co-Authored-By: WendellAdriel <wendelladriel.ti@gmail.com> * Improve translation Co-Authored-By: WendellAdriel <wendelladriel.ti@gmail.com> * Improve translation Co-Authored-By: WendellAdriel <wendelladriel.ti@gmail.com> * Improve translation Co-Authored-By: WendellAdriel <wendelladriel.ti@gmail.com> * Improve translation Co-Authored-By: WendellAdriel <wendelladriel.ti@gmail.com> * Improve translation Co-Authored-By: WendellAdriel <wendelladriel.ti@gmail.com> * Improve translation Co-Authored-By: WendellAdriel <wendelladriel.ti@gmail.com> * Improve translation Co-Authored-By: WendellAdriel <wendelladriel.ti@gmail.com>
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) |
* Update docs for stable Hooks * Add Hooks to reference page * Reword intro * Tweak refwording * Hooks blog post draft * Link to roadmap from post * Add more details * Update and rename 2019-01-30-react-v16.8.0.md to 2019-02-04-react-v16.8.0.md * changelog updates * review tweaks * Mention type defs * add warning for invalid hook call * Warning page for invalid Hook calls (reactjs#1613) * add warning for invalid hook call * Fix versions * Split code examples * unnecessary comma * tweaks * Update content/warnings/invalid-hook-call-warning.md Co-Authored-By: gaearon <dan.abramov@gmail.com> * nit * Update 2019-02-04-react-v16.8.0.md * Thanks Sophie * Update 2019-02-04-react-v16.8.0.md * Revert "add warning for invalid hook call" This reverts commit e301239. * Tweaks * Docs updates * Point to codesandbox and usehooks as community examples * tweaks * testing * Renamed Hooks blog/date * Udpated changelog * Replaced inaccurate comments * Added ReactTestUtils.act() to CHANGELOG * Moved blog post to Feb 6th * Update version number in header and versions page * Updated 16.8 CHANGELOG wording to also mention ReactTestRenderer.act() * Fix typo on hooks availability Might make people that are going through the docs confused. * React Native will ship hooks in its 0.59 release. (reactjs#1633) * Added link to 16.7 docs * Port external gatsby-remark-autolink-headers plugin * Implement custom-id syntax on headings * Replace keys when inserting style/script tags * react-testing-library now supports `act` (reactjs#1635) * react-testing-library now supports `act` * fix typo * Document test renderer act (temporary fix) * Use 16.8.1 (reactjs#1638)
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!
The text was updated successfully, but these errors were encountered: