From e06fba6f7d4cc5433b0cb01a5f0a132521694bc2 Mon Sep 17 00:00:00 2001 From: Miles Reiter Date: Tue, 13 Feb 2024 14:05:20 -0500 Subject: [PATCH] Accessibility Guide (#2832) * Delete rafts-accessibility-dos-and-donts.md * Update README.md * Create accessibility-guide.md * Update accessibility-guide.md Cleans up some inline link markup * Update accessibility-guide.md --- docs/Technical-Documentation/README.md | 2 +- .../accessibility-guide.md | 236 ++++++++++++++++++ .../rafts-accessibility-dos-and-donts.md | 53 ---- 3 files changed, 237 insertions(+), 54 deletions(-) create mode 100644 docs/Technical-Documentation/accessibility-guide.md delete mode 100644 docs/Technical-Documentation/rafts-accessibility-dos-and-donts.md diff --git a/docs/Technical-Documentation/README.md b/docs/Technical-Documentation/README.md index 31d6a3214..e6ef1b203 100644 --- a/docs/Technical-Documentation/README.md +++ b/docs/Technical-Documentation/README.md @@ -19,7 +19,7 @@ This directory contains system and architecture documentation including diagrams - [jwt-key-rotation.md](./jwt-key-rotation.md) : Describes the process for rotating JWT keys in Login.gov. - [nexus-repo.md](./nexus-repo.md) : Setup, connection information, and how to use our Nexus Artifact Repository - [openid-connect.md](./openid-connect.md) : Provides an architecture-level view of the OpenID Connect prototocol. -- [rafts-accessibility-dos-and-donts.md](./rafts-accessibility-dos-and-donts.md) : A succint list of UX guidelines for frontend accessibility. +- [accessibility-guide.md](./accessibility-guide.md) : A guide on getting started with accessibility testing tools and TDP-relevant resources. - [remote-development.md](./remote-development.md) : A guide on doing live remote development in Cloud.gov. - [unit-tests.md](./unit-tests.md) : Outlines our unit testing frameworks and how to run these manually. - [user_role_management.md](./user_role_management.md) : Provides an overview of our user management in Django Administrator Console. diff --git a/docs/Technical-Documentation/accessibility-guide.md b/docs/Technical-Documentation/accessibility-guide.md new file mode 100644 index 000000000..ae938ef1f --- /dev/null +++ b/docs/Technical-Documentation/accessibility-guide.md @@ -0,0 +1,236 @@ +# Accessibility Guide + +**Table of Contents:** +- [Background](#Background) +- [Relevant standards](#Relevant-standards) +- [State of a11y in TDP](#State-of-a11y-in-TDP) +- [What to keep in mind when testing](#What-to-keep-in-mind-when-testing) +- [Testing tools](#Testing-tools) +- [Screen reader use and setup](#Screen-reader-use-and-setup) +- [Do's and don'ts when designing](#Dos-and-donts-when-designing) +- [References](#References) + +--- + +## Background +This document has evolved from its initial state of "Helpful a11y stuff" to one intended to serve more as a guided tour of Raft's accessibility (a11y) practice aimed at enabling more testing and broadly more *consideration* of a11y to be shifted left. + +Additionally, this resource will also aim to document the current state of a11y in TDP to track outstanding enhancements or a11y fixes and to help commentate some issues that may be encountered when testing TDP pages for accessibility conformance. While TDP remains highly accessible as a whole there are certain issues we've identified that demand follow-on work to research or correct. There are also a number of false positives that certain a11y testing tools can identify as problematic. + +--- + +## Relevant standards +There are numerous areas of accessibility law that apply to our work ranging from the ADA (Americans with Disabilities Act) which lays out the broad requirement of accessibility in public spaces and systems to Section 508 of the Rehabilitation Act which mandates a specific standard that Federal systems & resources need to adhere to—specifically WCAG (Web Content Accessibility Standards) 2.0 AA. [See more on US accessibility law](https://www.ada.gov/resources/disability-rights-guide/#top). + +WCAG 2.x standards have four categories with which to evaluate accessibility; Perceivable, Operable, Understandable, and Robust. Within all four categories are three levels of conformance, A, AA, AAA; respectively these correspond to the most barebones standards, good baseline standards, and the most specific standards. + +--- + +## State of a11y in TDP +The [errors audit](https://hackmd.io/79rAOVzISbOvaTNv8nSpeA) tracks all outstanding accessibility issues in the TANF Data Portal, its knowledge center, and Django Admin console. + +--- + +## What to keep in mind when testing +The full picture of what makes for *complete* accessibility testing involves every check in Accessibility Insight's Full Assessment tool, thoughtfulness around what makes for a good experience through the lens of various assistive technologies, and real-world usability testing with people experiencing disabilities. This guide isn't going to be able to deliver all that—but it will seek to lay out some illustrative examples and frequently useful questions to pose of an experience when you're testing it for conformance. + +The following checklist is organized via WCAG 2.x's categories. While a few items explicitly involve screen-readers or other assistive technologies, most items should be able to be checked "yes" regardless of your mode of interaction with the webpage (vision & mouse, keyboard only, screenreader, etc...). + + +### Is it Perceivable? +The user must be able to *perceive* all the information being presented. + +- [ ] If there are non-decorative images on the page, do they have alt-text? + - [ ] Does the alt text convey all the relevant information a sighted user would get from the image? +- [ ] Is there a visible focus indicator for every element of the interface as you tab through it? +- [ ] Do all interface items have sufficient contrast against their backgrounds? + - [ ] If information is communicated by color are there also alternatives beyond color for folks who can't see or distinguish the colors? +- [ ] Do related areas of the interface have visual proximity to each other? +- [ ] Are all interface items read correctly by screenreaders? + +### Is it Operable? +The user must be able to *use* all interactive portions of the experience—and navigate to all areas of it. + +- [ ] When navigating the page with the keyboard can you tab to every interactive element? + - [ ] Is the order in which items are focused logical? + - [ ] If there's a disabled element is it correctly marked up with ARIA and read to screen readers? +- [ ] Is there sufficient (read as: generous) time to read and interact with transient elements of the page (e.g. the timeout modal dialog)? +- [ ] Does the navigable experience "shrink" when pop-over content is open? (e.g. Modal dialogs & the opened side navigation) + - [ ] Is content behind the pop-over content shaded out? + - [ ] Is keyboard focus constrained to the pop-over content alone? + +### Is it Understandable? +The user must be able to understand the information being presented by the experience and *how* to operate it. + +- [ ] Is the language used on the page [plain](https://www.plainlanguage.gov/guidelines/) rather than technical or overcomplicated? + - [ ] Are abbreviations defined alongside their first usage? + - [ ] Are unusual words explained? +- [ ] Do interface elements used for navigation appear and behave consistently throughout the experience? +- [ ] Does the experience make it clear when elements or page contexts change? (e.g. When you navigate to a new page or a new piece of content appears) +- [ ] Are there labels and instructions on the page to help prevent errors? + - [ ] When errors appear is it clear what action or form item they relate to? + - [ ] When errors appear do they suggest something for the user to try next to correct or move past them? + +### Is it Robust? +The experience and the content within it need to be *reliable* and play nicely with a range of assistive technologies. + +- [ ] Does this experience work as intended when navigated via Safari and Voiceover? + - [ ] Does it work as intended when tested in other browsers and via other screen readers? +- [ ] Is the page parsed correctly by testing tools? + + +--- + +## Testing tools + + + + +### In-browser tools + +| Extension | Description | Link | +| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| **Alt-text tester** | Flags images on a page that are missing alt text, provides an easy way to view alt text for any image that has it. | [Chrome](https://chrome.google.com/webstore/detail/alt-text-tester/koldhcllpbdfcdpfpbldbicbgddglodk?hl=en) | +| **Accessibility Insights** | Great for getting familiar with WCAG. It has both fast-pass assessments and a guided way to do manual testing. Plus—when doing manual testing—deep dive explainers on each test (see the info buttons next to the headings of any given test). | [Chrome](https://chrome.google.com/webstore/detail/accessibility-insights-fo/pbjjkligggfmakdaogkfomddhfmpjeni), [Edge](https://microsoftedge.microsoft.com/addons/detail/ghbhpcookfemncgoinjblecnilppimih) | +| **Axe DevTools** | Great fast-pass scanner, will identify best practice issues as well as WCAG compliance violations. | [Chrome](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US), [Firefox](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/), [Edge](https://microsoftedge.microsoft.com/addons/detail/axe-devtools-web-access/kcenlimkmjjkdfcaleembgmldmnnlfkn) | +| **Accessible Colors** | Web tool tool that will tell you whether two hex codes have sufficient contrast with each other, show you what they look like, and suggests the closest alternative color if they don't have sufficient contrast. Note that the default values for font size, weight, and compliance can be left alone for most purposes. | [Site](https://accessible-colors.com/) | + + +If you go through all the manual tests in the full Accessibility Insights assessment having these scripts bookmarked will be useful! Running them is as simple as opening the bookmark while viewing the page you're testing. + +**Tests whether page text can be spaced out and comply with requirements without breaking layout** + +```` +javascript:(function(){ var style = document.createElement(%27style%27), styleContent = document.createTextNode(%27* { line-height: 1.5 !important; letter-spacing: 0.12em !important; word-spacing: 0.16em !important; } p{ margin-bottom: 2em !important; } %27); style.appendChild(styleContent ); document.getElementsByTagName(%27head%27)[0].appendChild(style); var iframes = document.querySelectorAll(%27iframe%27);for (var i=0; i";break;case Node.COMMENT_NODE:b+="<\!--"+a.nodeValue+"--\>";break;case Node.DOCUMENT_TYPE_NODE:b+="\n"}a=a.nextSibling}return b}(document),d=document.createElement("form");d.method="POST";d.action="https://validator.w3.org/nu/";d.enctype="multipart/form-data";d.target="_blank";d.acceptCharset="utf-8";c("showsource","yes");c("content",e);document.body.appendChild(d);d.submit()})(); +```` + +**Filters results of the above to only WCAG 2.0 violations** + +```` +javascript:(function(){var removeNg=true;var filterStrings=["tag seen","Stray end tag","Bad start tag","violates nesting rules","Duplicate ID","first occurrence of ID","Unclosed element","not allowed as child of element","unclosed elements","not allowed on element","unquoted attribute value","Duplicate attribute"];var filterRE,root,results,result,resultText,i,cnt=0;filterRE=filterStrings.join("|");root=document.getElementById("results");if(!root){alert("No results container found.");return}results=root.getElementsByTagName("li");for(i=0;i