Research Section 508 (accessibility) compliance

[cecilia-donnelly]

In what ways is the PSM currently not compliant with Section 508? What would we need to do to become compliant? Is this related to #238?

[brainwane]

Starting on this now.

[brainwane]

I started looking into this today. Here's my current thinking.

• We have a web application and some digital publications in PDF/ePub/Word, plus some emails we emit. We'll have to work on the accessibility of those documents, but the web app (including the emails we send) is the biggest deal and the top priority.
• We'll find a linter and connect it to Selenium/Serenity and have Travis run it to find a lot of issues in an automated fashion. That is related to Templatize UI #238 because the automated accessibility (a11y) tools often look for elements within the rendered HTML and the CSS/JS such that putting a11y stuff in the templates will be a one-stop shop to fix certain classes of problem.
• We'll use stuff like https://squizlabs.github.io/HTML_CodeSniffer/ as developers to make course corrections as we make changes. It's a bookmarklet. I click it when I'm on a page and it has a nice-looking widget spring up to tell me about accessibility issues on that page. And I can choose for it to specifically tell me about ADA (Section 508) issues, and just errors versus warnings. We can add something about that to CONTRIBUTING.md.

Next up: finding the right linter to plug into Gradle, ideally.

[brainwane]

Checklist for developers to consider (maybe put this in CONTRIBUTING.md): https://www.section508.gov/content/build/website-accessibility-improvement/major-web-issues (if this isn't good enough, I'll take another look through https://www.section508.gov/content/build/website-accessibility-improvement ).

A bunch of the automated tools that seem to exist for a11y testing to comply with Section 508 are closed-source, or obsolete, or only exist as browser toolbars or analyze-a-single-page-at-a-time scanners. I've found this 18F guide, the W3 Accessibility Evaluation Tools List, and this VA "course" helpful. I also need to look at this interagency list of resources.

Considering:

• Deque's tool axe-core
• a11ym
• pa11y-ci

[brainwane]

Most if not all of the currently-maintained FLOSS automated accessibility checking tools are written in Node.js, Ruby, or other languages that are NOT Java, Python, or Go. So we'll probably at least start by using git commit hooks or some other method for running them, rather than right away trying to get them into our Travis build process.

[brainwane]

After learning to use npm better (e.g., where packages live), I've started trying out pa11y and a11ym. pa11y is the core of pa11y-ci which is intended to integrate with continuous integrations, but one can run pa11y on its own, against a live webpage or a local saved one, and can filter results so it only tells you about Section 508 issues. Example:

$ pa11y -s Section508 file:///tmp/ProviderTypePage.html 
Welcome to Pa11y

 > PhantomJS browser created
 > Testing the page "file:///tmp/ProviderTypePage.html"

Results for file:///tmp/ProviderTypePage.html:

 • Notice: Ensure that the img element's alt text serves the same purpose and presents the same information as the image.
   ├── Section508.A.Img.GeneralAlt
   ├── #mainContent > div > div:nth-child(1) > a > img
   └── <img src="ProviderTypePage_files/psm-logo.png" alt="Provider Screening Module">

 • Error: Anchor element found with a valid href attribute, but no link content has been supplied.
   ├── Section508.L.NoContentAnchor
   ├── #enrollmentQuickSearch
   └── <a id="enrollmentQuickSearch" href="http://localhost:8080/cms/provider/search/quick" class="search"></a>

 • Notice: If an input error is automatically detected in this form, check that the item(s) in error are identified and the error(s) are described to the user in text.
   ├── Section508.N.Errors
   ├── #enrollmentForm
   └── <form action="" id="enrollmentForm" method="post"> ...</form>

 • Notice: Check that descriptive labels or instructions (including for required fields) are provided for user input in this form.
   ├── Section508.N.Labels
   ├── #enrollmentForm
   └── <form action="" id="enrollmentForm" method="post"> ...</form>

 • Notice: Ensure that this form can be navigated using the keyboard and other accessibility tools.
   ├── Section508.N.KeyboardNav
   ├── #enrollmentForm
   └── <form action="" id="enrollmentForm" method="post"> ...</form>

 • Warning: Semantic markup should be used to mark emphasised or special text so that it can be programmatically determined.
   ├── Section508.D.H49.B
   ├── #enrollmentForm > div:nth-child(1) > div:nth-child(1) > div > span > b
   └── <b>:</b>

 • Error: Anchor element found with a valid href attribute, but no link content has been supplied.
   ├── Section508.L.NoContentAnchor
   ├── #saveAsDraftModal > div > div:nth-child(1) > div > div > a
   └── <a href="javascript:;" class="closeModal"></a>

 • Error: Anchor element found with a valid href attribute, but no link content has been supplied.
   ├── Section508.L.NoContentAnchor
   ├── #practiceLookupModal > div > div:nth-child(1) > div > div > a
   └── <a href="javascript:;" class="closeModal"></a>

 • Notice: If an input error is automatically detected in this form, check that the item(s) in error are identified and the error(s) are described to the user in text.
   ├── Section508.N.Errors
   ├── #practiceLookupForm
   └── <form action="/cms/provider/enrollment/lookup" id="practiceLookupForm"> <span>...</form>

 • Notice: Check that descriptive labels or instructions (including for required fields) are provided for user input in this form.
   ├── Section508.N.Labels
   ├── #practiceLookupForm
   └── <form action="/cms/provider/enrollment/lookup" id="practiceLookupForm"> <span>...</form>

 • Notice: Ensure that this form can be navigated using the keyboard and other accessibility tools.
   ├── Section508.N.KeyboardNav
   ├── #practiceLookupForm
   └── <form action="/cms/provider/enrollment/lookup" id="practiceLookupForm"> <span>...</form>

 • Notice: This table has no headers. If this is a data table, ensure row and column headers are identified using th elements.
   ├── Section508.G.TableHeaders
   ├── #practiceLookupTableTemplate
   └── <table class="hide" id="practiceLookupTableTemplate"> <tbody> <tr> ...</table>

 • Error: Anchor element found with a valid href attribute, but no link content has been supplied.
   ├── Section508.L.NoContentAnchor
   ├── #staleTicket > div > div:nth-child(1) > div > div > a
   └── <a href="javascript:;" class="closeModal"></a>

 • Error: Anchor element found with a valid href attribute, but no link content has been supplied.
   ├── Section508.L.NoContentAnchor
   ├── #supersededTicket > div > div:nth-child(1) > div > div > a
   └── <a href="javascript:;" class="closeModal"></a>

 • Error: Anchor element found with a valid href attribute, but no link content has been supplied.
   ├── Section508.L.NoContentAnchor
   ├── #submitEnrollmentModal > div > div:nth-child(1) > div > div > a
   └── <a href="javascript:;" class="closeModal"></a>

 • Warning: Img element is marked so that it is ignored by Assistive Technology.
   ├── Section508.A.Img.Ignored
   ├── #printModal > div > div:nth-child(1) > a:nth-child(1) > span > span > img
   └── <img src="ProviderTypePage_files/icon-x.png" alt="">

 • Warning: Img element is marked so that it is ignored by Assistive Technology.
   ├── Section508.A.Img.Ignored
   ├── #printModal > div > div:nth-child(1) > a:nth-child(2) > span > span > img
   └── <img src="ProviderTypePage_files/icon-print2.png" alt="">

 • Warning: Img element is marked so that it is ignored by Assistive Technology.
   ├── Section508.A.Img.Ignored
   ├── #definitionsModal > div > div:nth-child(1) > a > span > span > img
   └── <img src="ProviderTypePage_files/icon-x.png" alt="">

 • Warning: Img element is marked so that it is ignored by Assistive Technology.
   ├── Section508.A.Img.Ignored
   ├── #NPIdefinitionModal > div > div:nth-child(1) > a > span > span > img
   └── <img src="ProviderTypePage_files/icon-x.png" alt="">

6 Errors
5 Warnings
8 Notices

a11ym provides a visual report dashboard that I think would be less useful for our purposes (see screenshot).

I am going to take some time this afternoon to spot-check some pages and make sure pa11y and https://squizlabs.github.io/HTML_CodeSniffer/ find all the Section 508 issues I can see. But if that works out, I'll suggest we start using a combination of those as we develop.

[PaulMorris]

Nice! pa11y seems like the better option. HTML_CodeSniffer looks good too.

[brainwane]

So I dug around a little and found that a11ym basically reuses pa11y, can be told to filter by Section 508 standards and output to the command line, but doesn't catch all the problems that pa11y does and has an odd problem with labelling items found as "undefined" and then not counting them correctly. So pa11y and potentially pa11y-ci seem more promising, along with the CodeSniffer (interestingly, the a11ym output includes " > Debug: Injecting HTML CodeSniffer" so perhaps it uses that too?).

[brainwane]

Incidentally, in case people wonder why this often comes up in the context of the Americans with Disabilities Act:

Under section 508 of the Rehabilitation Act of 1973, Federal agencies are required to make their Web sites accessible. 29 U.S.C. 794(d); 36 CFR 1194.....Although the language of the ADA does not explicitly mention the Internet, the Department has taken the position that title II covers Internet Web site access.

[cecilia-donnelly]

@brainwane reported the following from her investigations:

Errors, warnings, and notices Sumana found:

• Anchor element found with a valid href attribute, but no link content has been supplied. Stuff like <a href=\"javascript:;\" class=\"closeModal\"></a>
• Check that descriptive labels or instructions (including for required fields) are provided for user input in this form. Stuff like <form action=\"/cms/provider/enrollment/lookup\" id=\"practiceLookupForm\">\n <span>...</form> and <form id=\"paginationForm\" action=\"/cms/provider/dashboard/list/filter\" method=\"get\">\n<div class=\"filterPanel\" style...</form>
• Ensure that the img element's alt text serves the same purpose and presents the same information as the image. Stuff like <img src=\"Dashboard-serv-admin_files/psm-logo.png\" alt=\"Provider Screening Module\">
• Ensure that this form can be navigated using the keyboard and other accessibility tools. Stuff like <form action=\"/cms/provider/enrollment/lookup\" id=\"practiceLookupForm\">\n <span>...</form>
• If an input error is automatically detected in this form, check that the item(s) in error are identified and the error(s) are described to the user in text. Stuff like <form action=\"/cms/agent/enrollment/approve\" method=\"post\" id=\"approvalForm\">\n\n <div ...</form>
• Img element is marked so that it is ignored by Assistive Technology. Stuff like <img src=\"Provider-Statement_files/icon-x.png\" alt=\"\">
• Img element missing an alt attribute. Use the alt attribute to specify a short text alternative. Stuff like <img id=\"__lpform_firstName_icon\" src=\"data:image/png;base64,iV[...]
• Semantic markup should be used to mark emphasised or special text so that it can be programmatically determined. Almost always <b>:</b>
• The heading structure is not logically nested. This h3 element should be an h2 to be properly nested. Stuff like <h3>The following problems were ide...</h3>
• This table has no headers. If this is a data table, ensure row and column headers are identified using th elements. Stuff like <table class=\"hide\" id=\"practiceLookupTableTemplate\">\n\t <tbody>\n\t <tr>\n\t ...</table>

Specifically, from these sample pa11y runs, she found:

• 5 Section508.A.Img.MissingAlt
• 3 Section508.D.HeadingOrder
• 44 Section508.L.NoContentAnchor

Sumana added that "there is a lot of repetition in the inaccessible bits of code, as in, it's things that happen over and over in the templates (e.g., <b>:</b>), image inclusions, the JavaScript to close a modal, the search box)." Following that, she noted, "I think that if we use grep to search for similar bits of code whenever we fix them in a single template then we'll be on solid ground for remediating across the codebase ..... of course we may find more, as this was just spot-checking several reasonably representative pages."