Accessibility checks

Page content:

postdoc test checks every page with axe against the WCAG 2.0, 2.1 and 2.2 level A and AA rules. axe looks at a page as it is when it loads. These checks go further: they look at the page in its dark colours, use it with the keyboard, open what's closed, and make its text larger.

Every page, in this order
  1. 1 As it loads axe checks it against the WCAG rules
  2. 2 Dark mode The contrast rules run again
  3. 3 Keyboard Tab goes from the top to the bottom
  4. 4 Menus Each menu and dialog is opened and closed
  5. 5 Larger text More spacing, then twice the size
Then, once: navigation without reloads A link is followed with the keyboard. The new page has to be announced, and Tab has to start at its top.

Dark mode

axe checks contrast in the colours the page has when it runs. So after the WCAG rules, Postdoc switches the page to its dark colours and runs the contrast rules again. Problems that only show in dark mode are reported as such:

txt
   In dark mode: aXe rule color-contrast (serious): Elements must meet minimum color contrast ratio thresholds
	In 1 element(s): .article figcaption

Postdoc switches the page the way its default theme does, by setting data-theme="dark" on <html>. In Chrome and Edge, it also makes prefers-color-scheme: dark media queries match. If your theme uses something else, such as a dark class, set it under a11y.darkMode:

postdoc.config.jsjs
export default {
  nightwatch: {
    pageChecks: {
      a11y: {
        darkMode: {
          // Adds the class to <html>. Any other attribute is set to the value.
          attribute: 'class',
          value: 'dark'
        }
      }
    }
  }
};

A page that has the same colours in dark mode isn't checked again. Set darkMode to false to turn this off.

The keyboard check

axe looks at each page as it is, without using it, so it can't tell whether a keyboard user can get around. The keyboard check does that part. It presses Tab from the top of the page to the bottom and fails the page when:

  • a Tab stop can't be seen when it has the focus: it is hidden, outside the window, cut off by a container or covered by another element, such as a sticky header
  • a Tab stop looks the same with and without the focus
  • a Tab stop has no accessible name
  • the focus gets trapped, so Tab keeps going round the same elements
  • a link goes nowhere, with href="#"
  • an element looks or acts like a control but can't take the focus: it has a role such as role="button", an onclick attribute or a pointer cursor
  • the first Tab stop isn't a skip link to the main content
txt
  Running /guide/install.html:
  ✖ NightwatchAssertError
   Keyboard: Tab stops that look the same with and without the keyboard focus (1)
	header > div.header-inner > button.menuButton ("Menu")

    Read More :
    https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html

Configure it under keyboard, or set keyboard to false to turn it off:

postdoc.config.jsjs
export default {
  nightwatch: {
    pageChecks: {
      keyboard: {
        // Don't require a skip link.
        skipLink: false,

        // Elements to leave out of the report, as CSS selectors.
        ignore: ['.carousel']
      }
    }
  }
};

The keyboard check, and the menus and dialogs check below, don't run in Safari, where Tab skips links unless a setting that WebDriver can't change is on. In Firefox on macOS, Tab skips links too unless the accessibility.tabfocus preference is 7. The bundled Nightwatch configuration sets it; if you use your own, set it there.

Menus and dialogs

Menus, dialogs and panels that a button opens are hidden when the page loads, so the checks above don't see them. This check opens each one with the keyboard, checks it and closes it again. It fails when:

  • pressing Enter doesn't open it, or aria-expanded doesn't say that it's open
  • the focus doesn't move into a modal dialog, or Tab moves it out to the page behind
  • Tab can't reach what opened
  • axe or the keyboard check finds a problem in what opened
  • Escape doesn't close a dialog, a menu or an overlay that covers the page, or the focus doesn't go back to the button after it
  • pressing Enter again doesn't close anything else, such as an accordion panel
txt
   Toggle header > button.menuButton ("Menu"): after Escape closes it, the focus is lost instead of going back to the button.

    Read More :
    https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html

The check finds the buttons by their attributes: aria-expanded="false", aria-haspopup, popovertarget or commandfor, and the <summary> of a closed <details>. A button that opens a dialog should have aria-haspopup="dialog", and one that shows an element should name it with aria-controls, which also tells the check what to look at.

A button that's on every page, such as a menu button, is checked once per window width. Configure the check under toggles, or set toggles to false to turn it off:

postdoc.config.jsjs
export default {
  nightwatch: {
    pageChecks: {
      toggles: {
        // The most buttons to open on a page.
        maxToggles: 10,

        // Buttons to leave out, as CSS selectors.
        ignore: ['.carousel button']
      }
    }
  }
};

Larger text and spacing

People who need larger text, or more space between lines and letters, set it in their browser. This check does the same and fails when a box cuts off text that fit before. It tries:

  • the text spacing of WCAG 1.4.12: a line height of 1.5, paragraphs 2em apart, letter spacing of 0.12em and word spacing of 0.16em
  • text twice as large, as a browser's text-only zoom makes it (WCAG 1.4.4)
txt
   Text: Text that gets cut off when it is twice as large (1)
	main > div.card ("Install with npm…"): cuts off 24px at the bottom

A box cuts off text when it has a fixed height or width and hides what overflows. Content that scrolls doesn't count, and neither does a box that already hides its content, such as a closed panel. Configure the check under text, or set text to false to turn it off:

postdoc.config.jsjs
export default {
  nightwatch: {
    pageChecks: {
      text: {
        // Only check text spacing.
        resize: false,

        // Elements to leave out, as CSS selectors.
        ignore: ['.logo']
      }
    }
  }
};

Navigation without reloads

When Postdoc shows the next page in place, it tells assistive technology what a page load would: it announces the new page's title, and moves the focus to the top of the page, so the next Tab starts there. This check makes sure that still works with your layouts and scripts. It follows a link with the keyboard and fails when the new page isn't announced, when its title differs from the one it has after a page load, or when Tab goes somewhere else than after a page load.

It runs once, after the page checks. It's skipped when session.disable_spa turns off navigation without reloads. Set navigation to false to turn it off yourself.

What the checks can't find

Automated checks find many accessibility problems, but not all of them. Whether the focus order makes sense, and how the site works with a screen reader, still need a person to try.

Edit this page on GitHub