[Docs: A11y] Add accessibility docs #9519
Conversation
|
Thank you! I definitely want to get some a11y docs in – this has been on my todo list for a while. I don't think we should attempt to do a full tutorial on how to make accessible web apps since it is almost unchanged in React from any other web app and I'm sure there are great tutorials out there already. How about we link to some external guides about accessible web apps generally (that discuss labels, ARIA, labels, tab order, screen reader–only content, etc)? Maybe you can find some high quality ones that are good. And we can consolidate into a single new page – probably not a whole section – explaining how those interact with React and discuss React DOM's support of aria-*, event handlers, tabIndex/htmlFor, and whatever else might be relevant. We can include a brief bit on designing accessible components (for example, it might be wise to have a required "label" prop and then having another prop to indicate whether that label is visible or hidden so that component users don't forget to add an accessibility label). I don't have a complete list in mind right now but hopefully that gives the right idea of what I'm imagining. What do you think? |
|
@spicyj Hey, thanks for the reply! Constantly finding such a general openness towards a11y in the React community and that is awesome, thank you! Sounds like a great idea indeed. Perhaps better not to reinvent the wheel here. For instance labelling: https://www.w3.org/WAI/tutorials/forms/labels/ Already have a pile of trusted resources I can sift through and see. Happy to run with this. Give me a few days or so to get my ducks in a row and will get back to further the discussion. |
|
cc @jessebeach @tatermelon for awareness :) |
|
Hello @AlmeroSteyn ! Great to see you in this repo as well!
Agreed. @tatermelon and @mcking65 are working on canonical examples for components in the https://github.com/w3c/aria-practices repository. I'd love to see us centralize our efforts to provide functional examples there.
Great, links to additional resources are very helpful. I'm sure @marcysutton @WilcoFiers and @dylanb would be glad for the mention of aXe. |
|
@AlmeroSteyn That outline looks great - I know this is nit-picking a bit (and also slightly off-topic) - but we don't recommend wrapped labels as the preferred method simply because it reduces the touch target size for putting focus into the input field. When you use for-id, then clicking the label text will place focus in the input - which is of course helpful for things that are small like radios or checkboxes. |
|
@jessebeach Likewise! Linking to external resources does indeed make more sense. I have a question, and I've had it for a while now. How would you bridge the "gap" between those examples there and using them in React components, especially for new devs? I often go to the ARIA pages to find examples and ideas but I can help myself in JavaScript, I love a11y and I know how components work, so the translation is relatively easy and I have a reason to take the time to do it. But the best accessible examples you can find are almost always imperative code. So I have been wondering how one can make it easier for the React dev, in this case, and how to make them aware. The number of devs I come across that even know these techniques and examples exist is far too low. I guess that is why my first instincts here were to rehash a bit of already published material but with "copy-and-pastable" accessible React code. If it already exists I have been unable to find it. An a11y doc here linking to these resources would certainly address the awareness aspect but I keep wondering if we don't need similar examples for React as well. However, I realise it is quite an undertaking and day job time constraints have prevented me from going solo down this path... What do you think? |
|
@dylanb Thank you for the info. Love learning more a11y caveats, so please nitpick away! Could you tell me in which OS/browser combinations this happens? Just did a double check (for my own sanity as I could swear I've seen it working haha) and clicking the wrapping label in Chrome, Firefox and IE on Windows does set the focus on the wrapped input? Or is it only for touch events? I see, however, that some AT may have issues with it: https://www.w3.org/TR/2008/WD-WCAG20-TECHS-20080430/H44.html Been advocating this as the best way in components as you don't need to generate unique Talking about I think mentioning how to best generate these would be a great thing to add to the React a11y page as it pertains directly to applying the HTML standard in re-usable components. What do you think? |
|
@AlmeroSteyn the beauty of accessibility is: as long as it works its allowed. I just went back and tested on OS X and all the browsers are working too. I also tested iOS and that is working. So I will retract my statement. |
|
@dylanb Thanks for letting me know! |
|
@dylanb Was reading the fine print in the W3C WAI document and:
Your recommendation to prefer explicit labeling still stands! |
|
@AlmeroSteyn I think that statement is a bit out of date (as was my understanding) - but you cannot go wrong with for-id :-) |
|
Just an update that I am still actively looking at this. Balancing act with day job work etc etc :-) |
AlmeroSteyn
force-pushed
the
a11y-docs
branch
6 times, most recently
from
2c94885
to
9f3164c
Compare
|
I have created a first draft doc. For now, there is very little code in it. Consists mainly of links showing how and some text putting it into perspective. @spicyj @jessebeach @dylanb Would any of you be able to have a quick look at it to see if it is going in the right direction? It would be great to know before I go think up React implementations and edge cases not covered by the references for each section :-) To cut the verbosity and make it easier at a glance ,here is the outline of the doc with only the reference links used in each section and all text stripped. Do you perhaps miss any good reference you know of? And is deep linking OK? Thanks so much in advance! Why accessibility?Standards and guidelines:WCAGWeb Content Accessibility Guidelines WAI-ARIAWeb Accessibility Initiative - Accessible Rich Internet Applications Accessible formsLabellingNotifying the user of errorsFocus controlKeyboard focus and focus outlineMechanisms to skip to desired contentSemantic HTML and screen readersSkiplinksProgrammatically managing focuskeyboard-navigable JavaScript widgets More complex widgets(https://www.w3.org/TR/wai-aria/roles)
Other points for considerationSetting the languageSetting the document titleColour contrast
calculate an entire accessible colour palette with Colorable. Development and testing toolsThe keyboardDevelopment assistanceeslint-plugin-jsx-a11yreact-axeTesting accessibility in the browseraXe by DequeWebAIM WAVEWeb Accessibility Evaluation Tool Accessibility inspectors and the Accessibility TreeAutomated accessibility testingScreen readersNVDA in FireFoxVoiceOver in Safari
JAWS in Internet ExplorerTesting colour contrast |
|
This is a good set of links. In toolsets like React (SPAs), the largest single problem is focus management. The reason this is different from normal keyboard and focus management is because the framework can/will change the DOM out from under the user and focus gets lost. It is also non-trivial to solve this problem in a React application. The focus management section needs to cover this as it is not covered well enough by the content you currently link to. |
|
The list of links is spot on. I really don't think you need much text around them. Any text should either answer:
Let W3C, WCAG, WAI-ARIA do the heavy lifting of background info and moralizing. This doc is a pragmatic list of tools and solutions. |
|
@dylanb Hmmm maybe it is because I try not go crazy with the DOM because of a11y but have not had much trouble with this myself in React. It seems to leave DOM elements untouched if there are not wild changes. Then again our apps are not wildly widget driven but focus more on forms and validation. Could you perhaps illustrate with a specific example? Would love to add that. I have had far more issues with ARIA live regions not firing when they should even when the DOM seems untouched. Worked it out here http://almerosteyn.com/2017/03/accessible-react-navigation and had to add timeouts or it would only work in Chrome with NVDA. |
|
@jessebeach Thank you for taking time to look at it! I will align the doc to that. and get back to you once there is a new draft. |
|
cross-reference to New Docs issue #8060 |
AlmeroSteyn
force-pushed
the
a11y-docs
branch
2 times, most recently
from
3548707
to
c054a06
Compare
|
Sorry for taking so long to get to the first review changes. @jessebeach I have stripped the text down and focussed on the links. As suggested by @dylanb I did go into more detail in the Please let me know what you think of where it is now. And is the |
docs/docs/accessibility.md
Outdated
|
|
||
| ## Why accessibility? | ||
|
|
||
| Web accessibility (also referred to as [**a11y**](https://en.wiktionary.org/wiki/a11y)) is the design and creation of websites that can be used by everyone. People who experience disabilities only fully benefit from websites when |
There was a problem hiding this comment.
"Accessibility support is necessary to allow assistive technology to interpret web pages."
There was a problem hiding this comment.
"People who experience disabilities only fully benefit from websites when they include accessibility features".
This phrase feels a bit contentious. I can't come up with a phrasing that doesn't have "othering" connotations or undertones of condescension. Let's just stick with a factful sentence about the technology as written above.
There was a problem hiding this comment.
Agreed. I was struggling with this myself when I wrote it. Trying to avoid 'othering' while coming up with something that would speak to the developer who so not know about a11y yet. This one won then but your signal is clear enough that the vote should have gone the other way. Thank you! Fixed in the next push.
docs/docs/accessibility.md
Outdated
|
|
||
| The [Web Content Accessibility Guidelines](https://www.w3.org/WAI/intro/wcag) provides guidelines for creating accessible web sites. | ||
|
|
||
| The following WCAG checklists can help in getting an overview: |
There was a problem hiding this comment.
"The following WCAG checklists provide an overview"
There was a problem hiding this comment.
Fixed in next push.
docs/docs/accessibility.md
Outdated
| - [WebAIM shows us how to label elements](http://webaim.org/techniques/forms/controls) | ||
| - [The Paciello Group explains accessible names](https://www.paciellogroup.com/blog/2017/04/what-is-an-accessible-name/) | ||
|
|
||
| Although these standard HTML practices can be directly introduced into React, note that the `for` attribute is written as `htmlFor` in JSX: |
There was a problem hiding this comment.
"directly used in React"
There was a problem hiding this comment.
Fixed in next push.
docs/docs/accessibility.md
Outdated
|
|
||
| ### Mechanisms to skip to desired content | ||
|
|
||
| Provide a mechanism to allow users to skip past content sections in your application as this assists and speeds up keyboard navigation. |
There was a problem hiding this comment.
Skip past navigation sections, not content sections, right?
There was a problem hiding this comment.
Yeah. Meant that, as in jump past sections I am not interested in. Fixed in next push :-)
docs/docs/accessibility.md
Outdated
|
|
||
| - [Deque University - HTML 5 and ARIA Landmarks](https://dequeuniversity.com/assets/html/jquery-summit/html5/slides/landmarks.html) | ||
|
|
||
| #### Skiplinks |
There was a problem hiding this comment.
Seems like a duplicate of section "Mechanisms to skip to desired content" above. Combine?
There was a problem hiding this comment.
This is currently a subsection of that section, together with Semantic HTML and screen readers. There I meant to convey that you can skip to these elements using the screen readers (like the rotor in VoiceOver). I have now combined both into the upper section. What do you think? Changed in the next push.
docs/docs/accessibility.md
Outdated
| ### Programmatically managing focus | ||
|
|
||
| Our React applications continuously modify the HTML DOM during runtime, sometimes leading to keyboard focus being lost or set to an unexpected element. In order to repair this, | ||
| we need to programmatically nudge the keyboard focus in the right direction. For example by resetting keyboard focus to a button that opened a modal window after it was closed. |
There was a problem hiding this comment.
"after that modal window is closed".
Dereference the anaphor.
There was a problem hiding this comment.
Fixed in next push.
docs/docs/accessibility.md
Outdated
|
|
||
| To set focus in React, we can use [Refs to Components](refs-and-the-dom.html) or [ReactDOM](react-dom.html). | ||
|
|
||
| Using refs: |
There was a problem hiding this comment.
I'm hesitant to include this example. We really shouldn't encourage folks to call focus on an element on an onClick event.
Maybe remove the example code and just point to react-aria-modal.
There was a problem hiding this comment.
Originally I had a different example but I ended up using this one as this exact example exists on the refs page in the docs. Perhaps it should be looked at, at some stage then.
I want to try and propose a compromise. And know when I started up with React this was something that took a while to sink in. So I have cut down the code to just show how you focus, instead of showing where you put the code. I still think that maybe it could help to get devs started quicker with focus management.
What do you think of the new code examples? If you still feel edgy about it I will remove it :-)
Changed in next push.
docs/docs/accessibility.md
Outdated
| the cancel button (preventing the keyboard user from accidentally activating the success action) and trap keyboard focus inside the modal, it also resets focus back to the element that | ||
| initially triggered the modal. | ||
|
|
||
| **Note:** While this is a very important accessibility feature, it is also a technique that should be used judiciously. Use it to repair the keyboard focus flow when it is disturbed, not to try and anticipate how |
There was a problem hiding this comment.
Thank you for including this note :)
docs/docs/accessibility.md
Outdated
| A number of tools exist that can run accessibility audits on web pages in your browser. Please use them in combination with other accessibility checks mentioned here as they can only | ||
| test the technical accessibility of your HTML. | ||
|
|
||
| #### aXe by Deque |
There was a problem hiding this comment.
Could be rolled into thereact-axe section above.
There was a problem hiding this comment.
Done, I have rolled all aXe related things into one section. All under the heading of Testing accessibility in the browser. As axe-core uses a browser DOM this is technically correct. Changed in next push.
docs/docs/accessibility.md
Outdated
| - [Activate the Accessibility Inspector in Chrome](https://gist.github.com/marcysutton/0a42f815878c159517a55e6652e3b23a) | ||
| - [Using the Accessibility Inspector in OS X Safari](https://developer.apple.com/library/content/documentation/Accessibility/Conceptual/AccessibilityMacOSX/OSXAXTestingApps.html) | ||
|
|
||
| ### Automated accessibility testing |
There was a problem hiding this comment.
Again, could be rolled into the react-axe section above.
docs/docs/accessibility.md
Outdated
| - [WebAIM - Using JAWS to Evaluate Web Accessibility](http://webaim.org/articles/jaws/) | ||
| - [Deque - JAWS Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/jaws-keyboard-shortcuts) | ||
|
|
||
| ### Testing colour contrast |
There was a problem hiding this comment.
Should be rolled into the "Colour contrast" section above.
There was a problem hiding this comment.
Done. Fixed in next push
|
@jessebeach Thank you so so much for the fast and detailed review. Really glad you liked it and quite excited to get this into the docs! I have made all the changes requested. The major ones requiring another review are:
Please let me know if there is anything else left to change. I'll get to it ASAP. |
|
If there is anything still outstanding on this PR I can pick it up ASAP to get it ready :-) |
There was a problem hiding this comment.
This is an awesome one-pager on modern accessibility development practice. Thank you @AlmeroSteyn !!
I had two nit comments. Nothing to delay an approve.
@gaearon, have your requested changes been addressed?
docs/docs/accessibility.md
Outdated
| ## Accessible forms | ||
|
|
||
| ### Labelling | ||
| Every HTML form contol, such as `<input>` and `<textarea>`, needs to be labelled accessibly. We need to provide descriptive labels that are not only visible but also exposed to screen readers. |
There was a problem hiding this comment.
"but ARE also exposed to screen readers".
Maybe just cut the last sentence altogether. Up to you. Labels aren't required to be visible, although it's definitely preferred.
There was a problem hiding this comment.
Hmmm good one. Left the sentence but cut the visible bit so as not to indicate something is dogma when it isn't. Also saw I invented a new word form contol which I then fixed.
docs/docs/accessibility.md
Outdated
| } | ||
| ``` | ||
|
|
||
| Or we could use ReactDOM to directly find and focus the element without a ref: |
There was a problem hiding this comment.
@spicyj, is ReactDOM.findDOMNode discourage in the latest best practice?
There was a problem hiding this comment.
Yes, it's discouraged. Let's leave this out.
There was a problem hiding this comment.
Removed the example.
docs/docs/accessibility.md
Outdated
|
|
||
| We can set this in React using the [React Document Title Component](https://github.com/gaearon/react-document-title). | ||
|
|
||
| ### Colour contrast |
There was a problem hiding this comment.
Nit: let's use American spelling everywhere for consistency
There was a problem hiding this comment.
Fixed the ones I could find not being American hehe
docs/docs/accessibility.md
Outdated
| - "docs/index.html" | ||
| --- | ||
|
|
||
| ## Why accessibility? |
There was a problem hiding this comment.
Nit: we generally use Capitalized Style for large headers. So that would be "Why Accessibility?"
docs/docs/accessibility.md
Outdated
|
|
||
| React fully supports building accessible websites, often by using standard HTML techniques. | ||
|
|
||
| ## Standards and guidelines: |
There was a problem hiding this comment.
Nit: no : in headers. Let's change to "Standards and Guidelines"
docs/docs/accessibility.md
Outdated
|
|
||
| The [Web Accessibility Initiative - Accessible Rich Internet Applications](https://www.w3.org/WAI/intro/aria) document contains techniques for building fully accessible JavaScript widgets. | ||
|
|
||
| Note that all `aria-*` HTML attributes are fully supported in JSX. |
There was a problem hiding this comment.
Might need a tiny one-line example here because they use a different convention than other JSX props.
There was a problem hiding this comment.
Changed it to include the following:
docs/docs/accessibility.md
Outdated
|
|
||
| Note that all `aria-*` HTML attributes are fully supported in JSX. | ||
|
|
||
| ## Accessible forms |
| <input id="namedInput" type="text" name="name"/> | ||
| ``` | ||
|
|
||
| ### Notifying the user of errors |
There was a problem hiding this comment.
Note: it's fine to not capitalize headers with ### and more so this one is good
There was a problem hiding this comment.
Noted. Also stepped through all ## headers and capitalized where required.
docs/docs/accessibility.md
Outdated
|
|
||
| <center><img src="/react/img/docs/keyboard-focus.png" alt="Blue keyboard focus outline around a selected link." /></center> | ||
|
|
||
| Only ever use CSS that removes this outline, for example by setting `outline:0`, if you are replacing it with another focus outline implementation. |
docs/docs/accessibility.md
Outdated
|
|
||
| The Mozilla Developer Network takes a look at this and describes how we can build [keyboard-navigable JavaScript widgets](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets). | ||
|
|
||
| To set focus in React, we can use [Refs to Components](refs-and-the-dom.html) or [ReactDOM](react-dom.html). |
There was a problem hiding this comment.
Let's remove ReactDOM reference here.
There was a problem hiding this comment.
Removed the example.
docs/docs/accessibility.md
Outdated
| the cancel button (preventing the keyboard user from accidentally activating the success action) and trap keyboard focus inside the modal, it also resets focus back to the element that | ||
| initially triggered the modal. | ||
|
|
||
| **Note:** While this is a very important accessibility feature, it is also a technique that should be used judiciously. Use it to repair the keyboard focus flow when it is disturbed, not to try and anticipate how |
There was a problem hiding this comment.
We have existing styling format for notes:
> Note:
>
> (note text)
Let's use it here too.
The "Note:" will be bolded automatically.
|
I have made the requested changes. @jessebeach , @gaearon Thank you so much for the detailed reviews here. Know you are busy so this is very much appreciated. React is such a pleasure to work with not only because of the tech itself but also because of the openness and attitude of the community. |
docs/docs/accessibility.md
Outdated
|
|
||
| Ensure that your web application can be fully operated with the keyboard only: | ||
|
|
||
| - [WebAIM talks about keyboard accessibility](https://webaim.org/techniques/keyboard/) |
There was a problem hiding this comment.
The cert failed for me here, does this website support SSL?
|
Thank you very much! |
|
@nhunzaker thank you so much for that comment! @gaearon this was only a pleasure to put together. |
* [Docs: A11y] Add accessibility docs * Fix the link * Replace link image * Tweak style
I want to make a proposal to add Accessibility documentation to the React docs.
Being a great fan of both accessibility and React, I have experienced how well React can be geared to easily adding accessibility features. Adding docs about it would maybe help with more accessible React apps being built out there.
As base for the proposal I have created a taste of the docs it would become. However, I would first like to test if this kind and style of accessibility docs would fit the vision of the maintainers before spending too much time on it.
Here is a snippet from a section of what I have already made:
I have gone for the Eutopia, with a section in the main menu being dedicated to accessibility. It is very hard to bring the necessary basics home in a one pager, I think. I know it is a big ask to add a major section to the docs but maybe it would be great to show off a11y as a first class concern in the docs.
So the sections I have in mind are:
Building accessible forms
Here I have already created a section on labelling but it needs to be extended with validation error texts.
Controlling focus
Showing how showing focus on form controls should be maintained and how one can ensure that keyboard users do not get frustrated by losing focus and how to bypass blocks of content in pages.
ARIA roles, states and properties
An overview of what ARIA is and how can be used to create more complex accessible widgets
Developer tools
A look at tooling that makes accessibility visible for developers. Examples would be browser a11y inspectors,
eslint-plugin-jsx-a11y,react-axe,aXeitself and a quick how to on screen readers.Looking forward to hearing your comments :-)