Accessibility Knowledge I Learned from Automatic Accessibility Testings with Cypress and cypress-axe

I wanted to use Cypress to run automatic accessibility tests with Cypress and cypress-awe on my Web Components project Cucumber Components. Before I wrote any tests for Cucumber Web Components, the test reported several serious a11y errors on the components documentation page itself. I need to fix these accessibility issue first before moving on to web components testing. So this is probably the best time to start a new article sharing the a11y errors and learn some accessibility knowledge.

1. <ul> and <ol> must only directly contain <li>, <script> or <template> elements.

Command:      a11y error!
Id:           list
Impact:       serious
Description:  Ensures that lists are structured correctly
Help:         <ul> and <ol> must only directly contain <li>, <script> or <template> elements
Helpurl:      https://dequeuniversity.com/rules/axe/4.7/list?application=axeAPI


failureSummary: "Fix all of the following:\n  List element has direct children that are not allowed: a, h2"
html: "<ul class=\"astro-RYJZJGVK\">"

This error here is I was using <a> tag and <h2> tag as direct children of <ul> element. So I need to move these two elements elsewhere.

./docs/src/components/LeftSidebar.astro
<ul class="astro-RYJZJGVK">
  <a href="#article" class="sr-only focus:not-sr-only skiplink">
    <span>Skip to Content</span>
  </a>
  <h2 class="astro-RYJZJGVK">Components</h2>
  <li class="astro-RYJZJGVK">
    <a href="/components/alert" class="astro-RYJZJGVK">Alert</a>
  </li><li class="astro-RYJZJGVK">
    <a href="/components/button" class="astro-RYJZJGVK">Button</a>
  </li><li class="astro-RYJZJGVK">
    <a href="/components/checkbox" class="astro-RYJZJGVK">Checkbox</a>
  </li><li class="astro-RYJZJGVK">
    <a href="/components/carousel" class="astro-RYJZJGVK">Carousel</a>
  </li>
  <!-- other existing li elements -->
</ul>

2. Ensures links have discernible text

Command:      a11y error!
Id:           link-name
Impact:       serious
Tags:         Array(9)
Description:  Ensures links have discernible text
Help:         Links must have discernible text
Helpurl:      https://dequeuniversity.com/rules/axe/4.7/link-name?application=axeAPI

failureSummary: "Fix all of the following:\n  Element is in tab order and does not have accessible text\n\nFix any of the following:\n  Element does not have text that is visible to screen readers\n  aria-label attribute does not exist or is empty\n  aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty\n  Element has no title attribute"
html: "<a href=\"/\" class=\"logo astro-RYJZJGVK\">\n\t\t\t<img src=\"/cucumber-components.svg\" role=\"presentation\" alt=\"\" class=\"astro-RYJZJGVK\">\n\t\t</a>"

The error is I didn’t add a discernible text inside my logo link.

<a href="/" class="logo">
  <img src="/cucumber-components.svg">
</a>

To fix this accessibility issue, I need to add a discernible text.

<a href="/" class="logo">
  <span class="sr-only">Cucumber Components Home Page</span>
  <img src="/cucumber-components.svg">
</a>

3. Ensure elements that have scrollable content are accessible by keyboard

Command:      a11y error!
Id:           scrollable-region-focusable
Impact:       serious
Description:  Ensure elements that have scrollable content are accessible by keyboard
Help:         Scrollable region must have keyboard access
Helpurl:      https://dequeuniversity.com/rules/axe/4.7/scrollable-region-focusable?application=axeAPI

failureSummary: "Fix any of the following:\n  Element should have focusable content\n  Element should be focusable"
html: "<pre class=\"language-html\">"

For codes snippets like below, they’re scrollable, so we need to add a tabindex=0 to allow keyboard access. Be sure to add a focus indicator in CSS as well.

<pre class="language-html" tabindex="0">
  <cc-select>
    <cc-option value="monday" text="Monday" aria-selected="true"></cc-option>
    <cc-option value="tuesday" text="Tuesday"></cc-option>
    <cc-option value="wednesday" text="Wednesday"></cc-option>
    <cc-icon icon="chevron-down" slot="suffix"></cc-icon>
  </cc-select>
</pre>