TWE Design System: add accessibility testing to Microsite

[joshfishman]

Overview

We need to setup testing for the Design System microsite so we can automate accessibility testing and ensure that the design system meets accessibility standards

Action Items

• [x] Research best practices for including a testing library in your project
• [x] Research the best testing library for our needs, a few ideas below
• [x] Select a library and include in the project
• [ ] Create documentation on how to test each UI commit,
• [ ] Add documentation to sub-page of software engineer team wiki

Resources/Instructions

• Google Sheet with Pa11y output
• Team Wiki
• selenium
• Google Lighthouse node
• Microsoft
• Pa11y
• Tanaguru

[aconstas]

Looking into creating a pre-commit hook with Husky and Pa11y. Commits will be blocked unless they pass the Pa11y accessibility test

[aconstas]

4/13/24 Is there a specific accessibility standard that we are trying to comply with? WCAG2A, WCAG2AA, or WCAG2AAA

What type of messages do we want from pa11y? notice? warning? error?

[aconstas]

Pa11y identified several issues with how mkdocs generates a page from markdown files. One notable error that was logged in my integrated terminal concerns an anchor <a> element in the HTML. The error message from pa11y stated: "Anchor element found with a valid href attribute, but no link content has been supplied."

It's unclear how mkdocs handles these elements internally, but pa11y flagged this as a problem because it can affect website accessibility.

Pa11y cited: WCAG2AA.Principle1.Guideline1_3.1_3_1.F68

Is this an error we are concerned about? Or should I have Pa11y ignore these types of errors?

[aconstas]

• Commits will no longer be blocked if they do not pass the Pa11y accessibility test
• Looking into the best way to organize and gather Pa11y error messages (CSV, some type of log, etc.)

Exported current Pa11y errors from microsite into Google Sheet (sheets separated by URL):

https://docs.google.com/spreadsheets/d/12YkgTAsDeNIn9DZApfZ478mMONlqnO0QTK3kjdFBmyU/edit?usp=sharing

[ExperimentsInHonesty]

• First step for documenting the notice/warnings/error: a comprehensive list of every one across all the current pages in the repo (static)
• Evaluate results, determining which of the list we are going to address and how
• once eval and plan is created, we will know what kind of ongoing notifications that we want
• tune the notifications
• decide what documentation we need about errors we intend to address

[ExperimentsInHonesty]

On the spreadsheet, make a tab for all the pages, and add a column to indicate which page, so that we can sort by type of error (in code column). This will help with the evaluation.

[aconstas]

Research

I looked for Visual Studio Code accessibility plug-ins and found none that would meet our needs. The plug-ins I did find were linters that would not export error/warning messages (e.g., Axe)

Moving Forward

• Continue with the setup for Pa11y
• Utilize Google Sheets API to store Pa11y output

Questions

• How should Pa11y output be handled with Google Sheets? Suppose there's a pre-existing Google sheet full of accessibility errors, and a dev modifies an existing microsite page to handle some of those errors. Is it possible to overwrite data for that specific microsite page within the sheet? Or should Pa11y test the entire microsite, and override the pre-existing Google sheet completely?

Comments

• for tuning notification in future: Automating Your Accessibility Tests

[ExperimentsInHonesty]

Next step is to the create the spreadsheet which is all the errors on one sheet.

[aconstas]

Created a single Google Sheet with errors from the entire microsite.

Findings

Code	Count	Message
WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.NoContent	1,337	Anchor element found with a valid href attribute, but no link content has been supplied.
WCAG2AA.Principle3.Guideline3_2.3_2_2.H32.2	8	This form does not contain a submit button, which creates issues for those who cannot submit the form using the keyboard.
WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.InputCheckbox.Name	6	This checkboxinput element does not have a name available to an accessibility API. Valid names are: label element, title undefined, aria-label undefined, aria-labelledby undefined.
WCAG2AA.Principle1.Guideline1_3.1_3_1.F68	28	This form field should be labelled in some way...
WCAG2AA.Principle1.Guideline1_4.1_4_3.G145.Fail	9	This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 3:1...
WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.InputText.Name	9	This textinput element does not have a name available to an accessibility API. Valid names are: label element, title undefined, aria-label undefined ...
WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.InputRadio.Name	10	This radioinput element does not have a name available to an accessibility API. Valid names are: label element, title undefined, aria-label undefined ...
WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.Textarea.Name	3	This textarea element does not have a name available to an accessibility API. Valid names are: label element, title undefined, aria-label undefined, aria-labelledby undefined.

[ExperimentsInHonesty]

@aconstas Please provide update

1. Progress: "What is the current status of your project? What have you completed and what is left to do?"
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures or links* (if necessary): "Add any pictures or links that will help illustrate what you are working on."

• remember to add links to the top of the issue if they are going to be needed again.

[aconstas]

1. Progress: Completed the collection of all errors from microsite. We need to discuss what errors we are focused on and what errors we can ignore. Then we need to discus the best way to implement the logging of the errors to Google Sheets.
2. Blockers: None
3. Availability: all week
4. ETA: 5/23 or sooner depending on when we can discuss
5. Pictures or links:
   Google Sheet