From c345ff95f7916c296880d8cdeb974ad24c6cbb7b Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Wed, 25 Nov 2020 11:22:50 -0800 Subject: [PATCH] Start a11y testing checklist in Forem docs (#11614) --- docs/frontend/accessibility.md | 22 ++++++++--- docs/tests/accessibility-tests.md | 64 ++++++++++++++++++++++++++++--- 2 files changed, 75 insertions(+), 11 deletions(-) diff --git a/docs/frontend/accessibility.md b/docs/frontend/accessibility.md index fca666fc5..389eb76f1 100644 --- a/docs/frontend/accessibility.md +++ b/docs/frontend/accessibility.md @@ -4,11 +4,13 @@ title: Accessibility # Accessibility -To make Forem the most inclusive community platform around, accessibility should be considered to enable people with disabilities to create and consume content. +To make Forem the most inclusive community platform around, accessibility should +be considered to enable people with disabilities to create and consume content. ## The Basics -Forem UI changes should consider accessibility wherever possible. This includes common requirements such as: +Forem UI changes should consider accessibility wherever possible. Common issues +to watch out for in frontend code: - [Adequate color contrast](https://webaim.org/articles/contrast/evaluating) - [Semantic structure and headings](https://webaim.org/techniques/semanticstructure/) @@ -19,7 +21,8 @@ Forem UI changes should consider accessibility wherever possible. This includes ## More Advanced Things -If you're working on something JavaScript-heavy or animated, there are a few additional considerations for accessibility: +If you're working on something JavaScript-heavy or animated, there are a few +additional considerations for accessibility: - [Forem Accessibility Tests](https://docs.forem.com/tests/accessibility-tests/) - [Intro to ARIA](https://webaim.org/techniques/aria/) @@ -28,9 +31,16 @@ If you're working on something JavaScript-heavy or animated, there are a few add - [Linting with eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y) - [Testing with Jest-axe](https://dev.to/bdougieyo/accessibility-testing-in-react-with-jest-axe-l7k) +## Accessibility Testing + +See a list of testing steps to follow during development or for a Pull Request +review on the +[Forem Accessibility Testing Docs](https://docs.forem.com/tests/accessibility-tests/). + ## Resources -There's a wealth of information out there to learn about digital accessibility! Here are some resources: +There's a wealth of information out there to learn about digital accessibility! +Here are some resources: - [W3C's Web Accessibility Initiative](https://www.w3.org/WAI/) - [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG21/) @@ -38,7 +48,7 @@ There's a wealth of information out there to learn about digital accessibility! - [WebAIM](http://webaim.org/) - [A11y Project](https://a11yproject.com) - [Deque University](https://dequeuniversity.com/) -- [React Accessibility Docs](https://reactjs.org/docs/accessibility.html) (most will apply to Preact) +- [React Accessibility Docs](https://reactjs.org/docs/accessibility.html) (most + will apply to Preact) - [The Importance of Manual Accessibility Testing](https://www.smashingmagazine.com/2018/09/importance-manual-accessibility-testing/) - [Accessibility Insights extension](https://accessibilityinsights.com) - diff --git a/docs/tests/accessibility-tests.md b/docs/tests/accessibility-tests.md index cd7cef81e..5d7fc9e0f 100644 --- a/docs/tests/accessibility-tests.md +++ b/docs/tests/accessibility-tests.md @@ -5,17 +5,18 @@ title: Accessibility Tests # Accessibility Tests Accessibility testing is a form of automated and manual testing that helps us -identify some of the potential accessibility concerns on Forem. +identify some of the potential accessibility concerns on Forem. See also, the +[Forem Frontend Accessibility docs](https://docs.forem.com/frontend/accessibility/). -Many a11y issues are not obvious to everyone who contributes to the Forem -project, therefore leaning on tools to help us identify these issues is a good -practice. +Many accessibility (a11y) issues are not obvious to everyone who contributes to +the Forem project, therefore leaning on tools to help us identify these issues +is a good practice. It's a good idea to use browser plugins while you're developing to keep an eye out for these issues, as well as including automated tests to catch regressions in future changes. -The [aXe devtools](https://www.deque.com/axe) extension is a great place to get +The [axe devtools](https://www.deque.com/axe) extension is a great place to get started. It works in both Firefox and Chrome. Use an extension like this one to find potential a11y issues in your workflow. @@ -34,3 +35,56 @@ in your unit tests with [jest-axe](https://github.com/nickcolley/jest-axe). If you're still curious [there are some great talks on accessibility for developers](https://www.youtube.com/watch?v=8E9AEZjglqI). + +## PR Review Checklist + +Pull Requests should include accessibility testing to prevent barriers from +making it into the codebase. Sometimes issues found may be out of scope for a +particular PR – those can be opened as separate issues to be followed up on. + +Test the functionality in Forem-supported browsers for accessibility impact: +Chrome and Firefox were popular for Windows screen reader users in 2019 +[according to WebAIM](https://webaim.org/projects/screenreadersurvey8/#browsers). +Safari is the most common choice for Voiceover users on the Mac, even if Chrome +is widely used for development. Mobile browsers are worth checking, too. + +1. Keyboard: navigate the page without using a mouse or trackpad. + - Can you reach and operate the interactive controls like menus, buttons, and + other widgets? + - Can you see your focus point on the screen, and does the focus style have + adequate contrast? + - Does your focus point get lost or hidden behind any layers with items + needing to be disabled/hidden? +1. Run a browser extension. + - Use [axe](https://deque.com/axe), + [Accessibility Insights](https://accessibilityinsights.io), Chrome's + Lighthouse Audit, or + [WAVE](https://chrome.google.com/webstore/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh) + to run accessibility tests in the DevTools. + - Prioritize relevant, higher-impact violations and issues first. +1. Test color contrast. + - Pay extra attention to color contrast findings in your browser extension + tests, since it's the most common accessibility issue on the internet. + - The + [Chrome color picker with contrast ratio line](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference#contrast) + and + [WebAIM contrast checker](https://webaim.org/resources/contrastchecker/) + are helpful tools for tweaking colors to meet + [WCAG requirements](https://webaim.org/articles/contrast/). + +### Additional accessibility tests for PR reviews + +1. Screen reader testing + - Get feedback from people who use screen readers regularly if at all + possible. + - Understand that if you're a new screen reader user, there might be a + learning curve that can impact your results. + - Navigate through a UI change using a screen reader such as Mac + [Voiceover with Safari](https://webaim.org/articles/voiceover/), and + [NVDA](https://webaim.org/articles/nvda/) with Firefox or Chrome on + Windows. +1. Zoom and magnification + - In the web browser, try zooming in from 200% to 500%. + - Would the layout or change of functionality be impacted by someone needing + to magnify their screen? Are there alternative styling or other solutions + that would make zooming any easier?