From 7ddf5e6b8520adb87fbcae0e06423e1e72bc0592 Mon Sep 17 00:00:00 2001
From: Xander Leatherwood <44583237+xman343@users.noreply.github.com>
Date: Tue, 15 Aug 2023 10:55:35 -0400
Subject: [PATCH] first draft of a11y documentation

---
 CONTRIBUTING.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 81bb6404479..1b17b52ae8a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -350,6 +350,64 @@ Notice how we do all of these things manually:
 
 We have full access to the [Cypress API](https://docs.cypress.io/api) so any additional interactions or custom logic can be easily added.
 
+### Accessibility testing
+
+We reuse our component examples for accessibility testing with
+a Cypress script that evaluates each of their iframes for accessibility
+violations. 
+
+#### Running accessibility tests
+
+In the terminal: 
+
+- Run the command `yarn workspace a11y test` to run all of the component tests in the `a11y\src` folder. This will include `Component.cy.tsx`, which tests all of the component examples in the `iTwinUI\examples` directory.
+
+In the Cypress GUI:
+
+1. From the monorepo root, run `yarn workspace a11y open`. This will open the Cypress control panel where you can run the tests.
+2. Choose a browser to evaluate your tests through, then press the `Start Component Testing in [YourBrowser]` button below.
+3. Select `Component.cy.tsx` to run the script that tests all of the component examples. Any additional component test you write and place into `a11y\src` will also be present here for testing.
+
+##### Your results
+
+In the terminal, a table will be produced for each violating component with the Axe rule ID being violated and its description. 
+
+In Cypress, if the component violates a Axe rule, its rule ID and the number of offending nodes will be output in a line in the testing window. You can click on the line to highlight the offending nodes in the test browser. 
+
+For more information on the Axe rule IDs and their meanings, visit [Deque University's list of Axe rules.](https://dequeuniversity.com/rules/axe/4.4/)
+
+#### Writing accessibility tests
+
+- Write an example usecase of the component with each of the features you want to evaluate for accessibility.
+- In `testing\a11y\src`, write the Cypress test for your component.
+The test file should look something like this: 
+
+```ts
+import * as React from 'react';
+import { YourExample } from 'examples';
+import { ThemeProvider } from '@itwin/itwinui-react';
+
+it('should have no WCAG violations', () => {
+  cy.mount(
+    <ThemeProvider theme='dark' style={{ height: '100vh' }}>
+      <YourExample />
+    </ThemeProvider>,
+  );
+  cy.injectAxe({
+    axeCorePath: Cypress.env('axeCorePath'),
+  });
+  cy.checkA11y(undefined, undefined, (violations) => {
+    const violationData = violations.map(({ id, help }) => ({
+      Component: name,
+      'Rule ID': id,
+      Description: help,
+    }));
+    cy.task('table', violationData);
+  });
+});
+```
+
+
 ---
 
 ## Pull Requests