Add accessibility data to each asset

[mattrosno]

Summary

Hill 1A reads:

An IBM Maker [designers, developers, product managers delivering to the IBM ecosystem] can discover and learn about resources [standards and components/patterns] in the system with confidence in their completeness, who maintains them and where they’re used.

A crucial aspect of completeness is knowing to what degree is each asset (e.g. component) accessible. After talking with Marc Johlic, we don't have to go to lengths for each asset to specify which WCAG rules they conform to (e.g. WCAG 2.1 AA.) Instead, accessibility can be reported on a binary basis where an asset is accessible if:

1. There are no violations when running the automated Equal Access Checker
2. You can manually keyboard navigate through the asset

This accessible value could be recorded as: not specified, yes, or no.

Per Marc, there's no need to require accessibility tests for high contrast, with screen readers, etc. at the component level. Although not required, the more we test (and communicate that the tests have happened), the better confidence we can instill for our users.

In addition to this, each asset can be documented with an accessibility tab that specifies what Carbon provides, design recommendations, and development considerations. Related open issues:

• Create and publish markdown templates for all asset documentation pages #794
• Render asset page tab content MDX #793
• Add asset page tabs to schema #792

Job stories

What value will this deliver?

• When I'm looking for an asset, I want to look at only assets that are stable and trustworthy so that I don't waste time with looking for assets that are unstable or that I and my development team won't trust. carbon-job-stories#27
• When referencing components and patterns maintained by different teams, I want them to be consistently classified so I don't have to remember multiple naming and classification schemes. carbon-job-stories#40
• When determining to use an asset, I want to understand its history and any studies, audits, and tests performed so I have confidence in using it. carbon-job-stories#76
• When publishing the documentation for component I maintain, I want to specify metadata such as its status, framework, platform, version, etc. so my users can fully qualify the asset and determine if it fits their needs or not. carbon-job-stories#46

Acceptance criteria

What requirements must be met to complete this request?

1. An entry is added to the asset schema so the asset maintainers can specify if the asset is accessible or not
2. Determine where we'd want to display accessibility status (e.g. catalog items, asset overview dashboard, etc.)
3. Determine if we'd want to filter by accessibility in the catalogs
4. Render accessibility status per designs in above two items
5. Document how to use the checker (could be a video or something that demonstrates how to ignore checker errors specific to Storybook)

Other considerations

• Is there any way we can link to CICD accessibility reports so if somebody wants to learn more, then can see exactly what's passing and failing?

[mattrosno]

If this is reported through the schema and Carbon config YML files, because YML files are committed into Git repositories, even though we're saving a binary "yes/no" value, we could look up Git history to determine when the accessibility status was last changed, and by who.

I don't expect that this would happen often. But, it's possible if wanting to do a manual audit of accessibility status over time.

[marcjohlic]

We discussed this epic on the Carbon Accessibility Guild call and everything was well received! 🎉

Two areas of discussion were whether a pass should be both keyboard operability AND accessibility checker - or just a clean run with the accessibility checker.

My team is going to discuss that further on our Monday planning call, but we (IBMa) were all pretty much in agreement that it should be both operability and checker (as stated in the Description above).

As a side note to that, there was talk about badge (icon) levels vs multiple badges/icons. For example: passed accessibility checker - one “badge”/icon, passed accessibility checker AND keyboard operability two badges/icons… OR if just one, would there be a multiple levels of that icon to show that multiple tests have been passed etc.

It's an interesting idea, but for this initial implementation I still prefer to keep it as simple as possible - one binary of yes, no, or not specified.

Josh said he’d be happy to provide some input around CI/CD automation.

[marcjohlic]

IBM Accessibility team met and concluded that we would like to stick with the original plan that at this initial stage accessibility will be reported on a binary basis where an asset is accessible when:

1. There are no violations when running the automated Equal Access Checker
2. You can manually keyboard operate all functions of the asset (Note this slight change in wording from what's in the original description of this issue)

This accessible value could be recorded as: not specified, yes, or no.

[mattrosno]

@marcjohlic thanks for following up! We have this queued up for the v1.1 release (if you have the public ZenHub extension installed you can see that in the right column.) We'll reach out when this is closer to getting in a sprint to confirm the plan.

[mattrosno]

@mbgower here's the issue for how we could add an accessibility status to each asset. Please let us know if you have any thoughts and suggestions.

[marcjohlic]

@mattrosno here's the link to the video that @mbgower and Jess Lin created for contributors on Accessibility testing components in Storybook. Let me know if you run into any Box issues accessing/downloading the video.