Switch from HTML_CodeSniffer to Axe Puppeteer

[aduth]

🛠 Summary of changes

Updates accessibility tests to use @axe-core/puppeteer instead of HTML_CodeSniffer, which has a much more thorough accessibility test suite and is more consistent with how we test accessibility in other Login.gov projects.

As part of this, updates were made to resolve preexisting accessibility issues:

• Update documented header markup to ensure all content is contained in landmark regions, and for consistency with documented USWDS component markup
• Ensure that scrollable code sections are keyboard-operable, by overriding default Kramdown Markdown HTML conversion

📜 Testing Plan

1. make build
2. node --test test/accessibility.test.js

[aduth]

This is "bare minimum". We could / should choose to omit .withTags(['wcag2a', 'wcag2aa']) which identifies several more "best practice" failures, but we can improve that iteratively.

Suggested change

	const results = await new AxePuppeteer(page).withTags(['wcag2a', 'wcag2aa']).analyze();
	const results = await new AxePuppeteer(page).analyze();

[zachmargolis]

Do we need to explicitly load this anywhere so it can take effect? I'd expect a _config.yml change listing this file. Or does it get magically loaded somehow?

[aduth]

Anything in _plugins is magically loaded by Jekyll, and this will override the module method from Kramdown referenced indirectly through Jekyll compilation.

I adapted this approach from similar plugins we use on some other sites like with how we add design system classes to Markdown links in the brochure site.

[aduth]

Visual regression failure is catching updated markup for header component.

[aduth]

This is "bare minimum". We could / should choose to omit .withTags(['wcag2a', 'wcag2aa']) which identifies several more "best practice" failures, but we can improve that iteratively.

Some notes for posterity / future self after looking at this a bit: It's complicated by the fact that many code examples assume an isolated environment from sibling code examples so issues like distinct aria-label for landmarks are flagged on pages where we show multiple variations of the same base markup. In practice we'd expect only one of those markups to be used on a site so that it wouldn't generate the issue.

Couple ideas for addressing this:

• Easier is to exempt certain "expected" violations for documentation pages after acknowledging it's not actually an issue
• Better would be to actually create that isolation with something like an iframe, similar to what was done in Add header documentation with mobile preview #418
  • Creating the frame page for every code example would be cumbersome to do manually.
  • As a solution, we could consider...
    • The dynamic injectable frame originally explored in Add header documentation with mobile preview #418 prior to ace14d0
    • A Jekyll plugin that generates new content in combination with a custom tag like {% code_example %}
      • It's not too hard to have a custom tag which renders Markdown and writes a new file, it's a little harder to place that rendered Markdown into an existing layout like the base.html layout
  • In either case, one additional complication of a dynamic frame is that unlike the static sizing of the mobile frame in Add header documentation with mobile preview #418, the frame would need to adjust to its own content, which would require a bit more work to talk (postMessage) between the iframe and the parent page to resize the frame after load.

The "Easier" option might be the best bet for a short-term solution, after timebox exploration.