Add accessibility checks for component documentation examples

[khiga8]

Fixes https://github.com/github/primer/issues/728
Looking into this as part of accessibility passion week ❤️
cc: @primer/accessibility

What are you trying to accomplish?

This PR introduces a GitHub Action workflow that conducts axe check on examples on the documentation site.
The script uses @axe-core/cli.

We run the documentation site and run axe checks on every iframe on the components and utilities pages.
We exclude rules that are dependent on full-page context as those don't make sense to check.

What approach did you choose and why?

• Created a needs_to_be_fixed list which represents starting point violations. We should fix this over time.
• Decided to go with @axe-core/cli because we don't have any browser tests that run doc examples. Introducing those seem high-effort. I'm also not familiar with pa11y, which is a similar, alternate option.

NOTE: the axe CLI will fail when called on a page without the specified element in --include. This is why we limit it to /components/ and /utilities/ path which are guaranteed (as of now) to have iframe elements we want to check.

What should reviewers focus on?

This workflow takes around 5 minutes to complete. Is that acceptable? Thoughts appreciated.

Are additional changes needed?

• No, this PR should be ok to ship as is. 🚢

[changeset-bot]

⚠️ No Changeset found

Latest commit: ca7717c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[khiga8]

I'm not familiar with pa11y so I went with axe and a custom bash script. I'm not sure which is "better" but it might be worth considering too.

[khiga8]

Here is an example failure: https://github.com/primer/css/runs/5836513128?check_suite_focus=true.

[khiga8]

@jonrohan, @simurai This is ready for a hopefully final review :)

I updated things a bit after thinking through @simurai feedback!

Unlike PRC or PVC docs, Primer CSS doc examples don't have dependencies on external code since it's just HTML and CSS. CSS changes shouldn't affect HTML semantics so I think we only really need to run axe on URLs that correspond to doc files that were modified rather than on every doc page for every update.

Changes:

• Added this handy action which allows us to skip steps in the axe workflow based on pattern matching of changed files. This allowed us to get rid of some unpleasant parsing/conditional logic from our bash script.
• We only run axe checks on urls that correspond to doc paths that were modified which gets passed in from the Action in the former step.

Example run of when there are multiple modified files. We only run axe on 2 urls that correspond to paths that were changed. Time: 3 min 25s

Example run of axe action early returning because there were no changes to doc paths we cared about. Time: 9s

If we decide it is useful to run full axe checks for every doc page on every PR run, we can always revert back to: bd9eb4b.

[khiga8]

I would love if we added this message as a comment to the PR as a future enhancement.
This will bring greater attention to the fact that axe check is being skipped on a doc page someone has updated.

[khiga8]

Learn more here: https://github.com/tj-actions/changed-files

[khiga8]

This STRING_OF_PATHS_WE_CARE_ABOUT will be passed in by the previous step.

[simurai]

Thanks for all the speed improvements. They sound great. 🏇

[khiga8]

Anything else I should do to get this merged? 🙏 @primer/css-reviewers