[Docs: A11y] Add accessibility docs

docs/_data/nav_docs.yml

@@ -50,6 +50,8 @@
       title: Web Components
     - id: higher-order-components
       title: Higher-Order Components
+    - id: accessibility
+      title: Accessibility
 - title: Reference
   items:
     - id: react-api

docs/docs/accessibility.md

@@ -0,0 +1,310 @@
+---
+id: accessibility
+title: Accessibility
+permalink: docs/accessibility.html
+prev: higher-order-components.html
+next: 
+redirect_from:
+  - "docs/index.html"
+---
+
+## Why accessibility?
+
+Web accessibility (also referred to as **a11y**) is the design of websites that can be used by everyone. 
+
+Often, people who experience disabilities find it difficult or impossible to use the internet due to easily correctable problems with the HTML and/or scripting on the website. This
+group of people is staggeringly large worldwide and runs into millions of people who experience and navigate the internet in ways different from visually clicking with a
+mouse. They make use of a variety of Assistive Technologies to also consume the internet.
+
+The good news is that we can easily build websites in React that can be used by the widest possible range of people out there. Accessibility features are often found in HTML itself and as 
+React fully supports all these features, they can be easily translated into your React components.
+
+## Standards and guidelines:
+
+### WCAG
+
+The [Web Content Accessibility Guidelines](https://www.w3.org/WAI/intro/wcag) is a document that provides guidelines for creating accessible web sites.
+
+Initially it can be a lot of information to consume for the newcomer. The following WCAG checklists can help in getting an overview:
+
+- [WCAG checklist from Wuhcag](https://www.wuhcag.com/wcag-checklist/)
+- [WCAG checklist from WebAIM](http://webaim.org/standards/wcag/checklist)
+- [Checklist from The A11Y Project](http://a11yproject.com/checklist.html)
+
+### WAI-ARIA
+
+The [Web Accessibility Initiative - Accessible Rich Internet Applications](https://www.w3.org/WAI/intro/aria) document, contains a set of techniques we, as React developers, can use to add
+accessibility features to the applications we build.
+
+All `aria-*` HTML attributes are fully supported in JSX.
+
+## Accessible forms
+
+Gathering information from users is a core function of many web applications out there. We need to build our forms in such a way that everyone will be able to interact with them. This can be done by following a couple of relatively simple principles.
+
+### Labelling
+The name of every HTML form control, such as `<input>` and `<textarea>`,  needs to be clear to the person using the form. Visually this is relatively easy to achieve, 
+but to be truly inclusive we also need to communicate these labels to screen readers (a well know type of assistive technology). 
+
+The following resources show us how to do this:
+
+- [The W3C shows us how to label elements](https://www.w3.org/WAI/tutorials/forms/labels/)
+- [WebAIM shows us how to label elements](http://webaim.org/techniques/forms/controls)
+
+We should not underestimate the importance of doing this. Even one unlabelled form field has the potential to completely block many people from using your application at all!
+
+Although these standard HTML practices can be directly introduced into React, note that the `for` attribute is written as `htmlFor` in JSX:
+
+```js{1}
+<label htmlFor="namedInput">Name:</label>
+<input id="namedInput" type="text" name="name"/>
+```
+
+### Notifying the user of errors
+
+Applications need to draw the user's attention to error conditions resulting from their interaction with the application. If the user is unable to recognise these 
+messages and react upon them, it can severely interfere with the use of the application. A lot of time and effort is spent in visually notifying people of 
+these errors but we also need to notify screen reader users.
+
+The following link shows us a number of techniques we can apply to ensure that all users see our form error messages:
+
+- [The W3C demonstrates user notifications](https://www.w3.org/WAI/tutorials/forms/notifications/)
+
+## Focus control
+
+The keyboard is not only an extremely important input device for many people who experience disabilities but is widely used by everyone. Ensuring that a web application is
+operable with keyboard alone is one of the most important factors in building accessible applications. 
+
+### Keyboard focus and focus outline
+
+Keyboard focus refers to the current element in the DOM that is selected to accept input from the keyboard. We see it everywhere as an outline similar to the that shown on the following image:
+
+<center><img src="/react/img/docs/keyboard-focus.png" alt="Blue keyboard focus outline around a selected link." /></center>
+
+Avoid any CSS that removes this outline, by for example setting `outline:0`, as this instantly renders an application inaccessible.
+
+Read more about this very important feature here:
+
+- [WebAIM talks about keyboard accessibility](https://webaim.org/techniques/keyboard/)
+
+### Mechanisms to skip to desired content
+
+When you use a mouse, it is very quick and easy to navigate to specific page regions so that you can interact with the content and elements there. For keyboard users it is 
+a often a totally different experience. If the person is also using a screen reader the problem becomes even more restrictive as each element and page section needs to be read back until the desired content is reached.
+
+These people need a way to quickly set keyboard focus in a specific page region by skipping other parts of the page content. You can easily provide users with this feature by applying the following two techniques.
+
+#### Semantic HTML and screen readers
+
+Semantic HTML is the use of meaningful HTML elements to describe the intention of the HTML as well as the page structure. HTML 5 has provided us with a number of previously unavailable
+semantic elements, such as `<section>` and `<aside>`. 
+
+Some of these elements, such as `<main>` and `<aside>`, are known as landmark elements as they can be used to define specific page regions. 
+
+Some sssistive technologies allow the user to quickly navigate to these regions if they are found in the HTML.
+
+Read more about the use of these elements to enhance accessibility here:
+
+- [Deque University - HTML 5 and ARIA Landmarks](https://dequeuniversity.com/assets/html/jquery-summit/html5/slides/landmarks.html)
+
+#### Skiplinks
+
+Skiplinks or Skip Navigation Links are hidden navigation links that only become visible when keyboard users interact with the page. This way they do not interfere with the visual
+design of your web page but provide a very powerful tool to enable the keyboard-only user to instantly jump to predefined regions on the page.
+
+They are very easy to implement with internal page anchors and some styling:
+
+- [WebAIM - Skip Navigation Links](http://webaim.org/techniques/skipnav/)
+
+### Programmatically managing focus
+
+Sometimes we need to programmatically nudge the keyboard focus in the right direction, for example returning focus to the element that triggered an event, such as opening a modal window.
+
+The Mozilla Developer Network shows how to do this and build [keyboard-navigable JavaScript widgets](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets)
+
+React provides [Refs to Components](/more-about-refs.html) that can be used to call `focus()` on relevant elements should it be required to programmatically change the keyboard focus. Avoid
+imperatively setting focus on elements in the HTML DOM.
+
+The [react-aria-modal](https://github.com/davidtheclark/react-aria-modal) is a great example of focus management. This is a relatively rare example of a fully accessible modal window. Not only does it set focus on 
+the cancel button (preventing the keyboard user from accidentally activating the success action) and trap keyboard focus inside the modal, it also sets focus back to the element that 
+initially triggered the modal.
+
+**Note:** While this is a very important accessibility feature, it is certainly a technique that should be used judiciously. Only do this if the standard focus flow behaviour renders the 
+application difficult to use. Trying to constantly anticipate how users go about using the web page and manipulating the focus based on these assumptions causes
+more harm than good.
+
+## More complex widgets
+
+We can certainly build fully functional and accessible websites using only the elements provided by HTML, but in modern web applications we often want to create more complex controls or widgets. React
+gives us the ability to create controls that do not exist in native HTML. 
+
+Although very powerful, we also need to take care that they are created accessibly as all the care we took in using 
+HTML properly can be undone by an inaccessible widget. Imagine a perfectly accessible page that cannot be reached because the navigation menu is not accessible.
+
+In our endeavour to build more accessible widgets we require knowledge of [ARIA Roles](https://www.w3.org/TR/wai-aria/roles) as well as [ARIA States and Properties](https://www.w3.org/TR/wai-aria/states_and_properties). 
+These are a toolboxes filled with HTML attributes that are fully supported in JSX and enable us to construct fully accessible, highly functional React components.
+
+Usually each type of widget has a specific design pattern and is expected to function in a certain way by users and user agents alike:
+
+- [WAI-ARIA Authoring Practices - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices/#aria_ex)
+- [Heydon Pickering - ARIA Examples](http://heydonworks.com/practical_aria_examples/)
+- [Inclusive Components](https://inclusive-components.design/)
+
+## Other points for consideration
+
+### Setting the language
+
+In order to choose the correct voice synthesizer, screen readers need to know what language the page text is written in. If not specified, the user of your application may hear
+a synthesized voice encoded for one language doing a bad impersonation of page text in another language where the screen reader should have selected the correct language setting instead.
+
+This is very easily corrected:
+
+- [WebAIM - Document Language](http://webaim.org/techniques/screenreader/#language)
+
+### Setting the document title
+
+The `<title>` tag is required in HTML documents. However, setting one generic title for your entire application is not sufficient for many users. 
+
+The title is easily available to every user out there and should describe the current location of the application so that people can orient themselves better within the application.
+
+In the following links we not only see why this important but also find a handy React component we can use to set the document title:
+
+- [WCAG - Understanding the Document Title Requirement](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-title.html)
+- [React Document Title Component](https://github.com/gaearon/react-document-title)
+
+### Colour contrast
+
+Any website containing text needs this text to be clearly understandable by all users. We have seen many techniques so far to expose these texts properly to assistive tecnologies,
+but the text should also be readable by people with low vision or in circumstances where reading off a screen is made more difficult by environmentally conditions, such as a room with high glare.
+
+This is where colour contrast comes in. All the texts on our pages need to have a colour of a sufficient contrast ratio over that of the background.
+
+The following links dive into colour contrast:
+
+- [WCAG - Understanding the Colour Contrast Requirement](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html)
+- [Everything About Color Contrast And Why You Should Rethink It](https://www.smashingmagazine.com/2014/10/color-contrast-tips-and-tools-for-accessibility/)
+- [A11yProject - What is Colour Contrast](http://a11yproject.com/posts/what-is-color-contrast/)
+
+It can be tedious to manually calculate the proper colour combinations for all cases in your website so instead you can [calculate an entire accessible colour palette with Colorable](http://jxnblk.com/colorable/).
+
+## Development and testing tools
+
+Imagine building your React website and not looking at the result in the browser at all. How successful would that be?
+
+The same goes for web accessibility. We cannot blindly apply the principles and hope that the result will be accessible. As you get more proficient with these techniques, the results 
+will become more predictable but we require tools with which we can verify whether the result is accessible.
+
+### The keyboard
+
+By far the easiest and also one of the most important checks is to test if your entire website can be reached and fully used with the keyboard alone. You accomplish this by:
+
+1. Plugging out your mouse.
+1. Using `Tab` and `Shift+Tab` to browse.
+1. Using `Enter` to activate elements.
+1. Where required, using your keyboard arrow keys to interact with some elements, such as menus and dropdowns. 
+
+### Development assistance
+
+A number of tools are available to check accessibility features in our React JSX code directly in the IDE. 
+
+Often intellisense checks are already provided in JSX aware IDE's for the ARIA roles, states and properties.
+
+#### eslint-plugin-jsx-a11y
+
+The [eslint-plugin-jsx-a11y](https://github.com/evcohen/eslint-plugin-jsx-a11y) plugin for ESLint provides development feedback regarding accessibility issues in your JSX. Many
+IDE's allow you to integrate these findings right into code analysis and source code windows.
+
+[Create React App](https://github.com/facebookincubator/create-react-app) has this plugin activated. A minimal number of rules are currently activate to ensure maximum compatibility with code
+and build systems, but you can easily activate them all and integrate the feedback into your IDE with the following configuration in your `package.json` file:
+
+```json
+"eslintConfig": {
+    "extends": [
+      "react-app",
+      "plugin:jsx-a11y/recommended"
+    ],
+    "plugins": [
+      "jsx-a11y"
+    ]
+  }
+```
+
+#### react-axe
+The [react-axe](https://github.com/dylanb/react-axe) module enables us to use the power of [axe-core](https://github.com/dequelabs/axe-core) directly in our React applications as we 
+develop. It reports accessibility findings directly to the browser console.
+
+### Testing accessibility in the browser
+
+A number of tools exist that can run accessibility audits on web pages in browser. We can, of course use these tools for our React applications too.
+
+It is worth noting that these tools can only check on technical accessibility issues and therefore they do not replace the human touch when it comes to completely auditing a website for accessibility. For instance,
+they will not and cannot check if the logical flow of you page makes sense, or if the keyboard focus has been applied correctly.
+
+#### aXe by Deque
+
+[The Accessibility Engine](https://www.deque.com/products/axe/) or aXe, is an accessibility inspector browser extension to run accessibility checks in your browser console.
+
+#### WebAIM WAVE
+
+The [Web Accessibility Evaluation Tool](http://wave.webaim.org/extension/) from WebAIM is another accessibility checker that shows, with page markers, when accessibility features or
+faults are found on a web page.
+
+#### Accessibility inspectors and the Accessibility Tree
+
+[The Accessibility Tree](https://www.paciellogroup.com/blog/2015/01/the-browser-accessibility-tree/) is a subset of the DOM tree that contains accessible objects for every DOM element that should be exposed to assistive technologies, such as screen readers. This is
+the way the browser communicates with these technologies. This is also how we communicate intent when we use ARIA, as ARIA alters the accessibility tree.
+
+In some browsers we can easily view the accessibility information for each element in the accessibility tree:
+
+- [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
+
+The core engine behind [The Accessibility Engine](https://www.deque.com/products/axe/) and [react-axe](https://github.com/dylanb/react-axe) can be used in our own code and automated tests.
+This version is called [aXe-core](https://www.deque.com/products/axe-core/) and includes integrations for Selenium.
+
+### Screen readers
+
+Whereas simulations and tests will bring us a long way in verifying the accessibility of the applications we build, nothing beats experiencing the effect first hand. It is highly recommended
+that you familiarise yourself with at least one screen reader and use it from time to time to check the accessibility of your applications.
+
+Please note that browser / screen reader combinations matter. A specific screen reader will typically be used with a specific browser as it connects more closely to the implementation
+of the accessibility tree in THAT browser. It is best to test your application in the browser best suited to your screen reader of choice.
+
+#### NVDA in FireFox
+
+[NonVisual Desktop Access](https://www.nvaccess.org/) or NVDA is an open source Windows screen reader that is widely used.
+
+Refer to the following guides on how to best use NVDA:
+
+- [WebAIM - Using NVDA to Evaluate Web Accessibility](http://webaim.org/articles/nvda/)
+- [Deque - NVDA Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts)
+
+#### VoiceOver in Safari
+
+VoiceOver is an integrated screen reader on Apple devices. 
+
+Refer to the following guides on how activate and use VoiceOver:
+
+- [WebAIM - Using VoiceOver to Evaluate Web Accessibility](http://webaim.org/articles/voiceover/)
+- [Deque - VoiceOver for OSX Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts)
+- [Deque - VoiceOver for iOS Shortcuts](https://dequeuniversity.com/screenreaders/voiceover-ios-shortcuts)
+
+#### JAWS in Internet Explorer
+
+[Job Access With Speech](http://www.freedomscientific.com/Products/Blindness/JAWS) or JAWS, is a prolifically used screen reader on Windows. 
+
+Refer to the following guides on how to best use JAWS:
+
+- [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
+
+Both the aXe and WAVE tools mentioned above also include colour contrast tests and will report on contrast errors.
+
+If you want to extend your contrast testing abilities you can use these tools:
+
+- [WebAIM - Color Contrast Checker](http://webaim.org/resources/contrastchecker/)
+- [The Paciello Group - Colour Contrast Analyser](https://www.paciellogroup.com/resources/contrastanalyser/)