Accessibility

Principle

A page works from the keyboard and from a screen reader: landmarks, one h1, a skip link, a visible focus ring, text at 4.5:1, and a name on every control. An axe scan of the rendered pages is part of review.

Why

Note

These failures are ordinary and they survive a visual check. A brand colour used as 16px text on white often sits near 2:1. Placeholder text at #b0b7bf on white is about 2:1. An input with no label is unnamed. outline: none removes the keyboard indicator.

Normal text under 24px, or under 18.5px bold, needs 4.5:1 against its background. Large text needs 3:1. A focus indicator needs 3:1 against the adjacent colours.

How

The document shell is <header>, <main id="main">, and <footer>. Navigation has an accessible name, from aria-label or a heading. The skip link is the first focusable control, points at the main element’s id, and stays visually hidden until :focus.

The page has one h1. Later headings do not skip a level. A reusable heading component takes the level as an argument.

Focus uses :focus-visible. The ring is at least 2px, with a 2px offset, in a colour that clears 3:1 against the pixels behind it. A triple ring (colour, gap, colour) is valid when the gap colour is a token.

Text colours are tokens that pass 4.5:1 on the surfaces where they sit. A mid-scale brand step is not body text on white until the pair is measured. Placeholder text is text and uses the same bar.

Every input, select, and textarea has a <label> tied to its id, or an aria-label where a visible label is wrong. A control that opens a panel is a <button>. aria-controls is the id of the panel, not the id of the bar the button sits in. Attributes are quoted: aria-hidden="true".

A carousel or dialog that sets aria-label also sets a role (region or dialog). aria-label on a plain div is not a name.

How to check

Tip

1. Static checks from the theme directory.

   grep -R -n -E 'outline:[[:space:]]*(none|0)\b' --include='*.css' .
   grep -R -n -E 'aria-hidden=[^"]' --include='*.php' .
   grep -R -n -E '<h1\b' --include='*.php' .

   outline: none fails unless the same rule, or a paired :focus-visible rule, draws a visible ring. Two <h1> templates that can render on one page need a stated reason.

2. Heading list from a saved response. One h1, no skipped level.

   grep -o -E '<h[1-6]\b[^>]*>' page.html

3. axe-core, in a container on the same Docker network as the site. The script rewrites document and asset requests to the container IP and sets the public Host header, so a sign-in proxy in front of the public hostname is not on the path. TARGET_IP is the WordPress container address. TARGET_HOST is the public hostname. PATHS is a comma-separated list.

   sudo docker run --rm --network <docker-network> \
     -v "$PWD:/work" -w /work \
     -e npm_config_cache=/work/.npm \
     -e TARGET_IP=<container-ip> \
     -e TARGET_HOST=<public-host> \
     -e PATHS='/,/a-key-page/' \
     mcr.microsoft.com/playwright:v1.56.1-noble \
     bash -lc 'npm install --no-fund --no-audit playwright@1.56.1 @axe-core/playwright && node scan.mjs'

   scan.mjs

   import { chromium } from "playwright";
   import AxeBuilder from "@axe-core/playwright";
   
   const ip = process.env.TARGET_IP;
   const host = process.env.TARGET_HOST;
   const paths = (process.env.PATHS || "/").split(",");
   const browser = await chromium.launch({
     args: ["--no-sandbox", "--disable-dev-shm-usage"],
   });
   const page = await browser.newPage();
   
   await page.route("**/*", async (route) => {
     const url = new URL(route.request().url());
     if (url.hostname !== host && url.hostname !== ip) {
       await route.continue();
       return;
     }
     const response = await route.fetch({
       url: `http://${ip}${url.pathname}${url.search}`,
       headers: {
         ...route.request().headers(),
         host,
         "x-forwarded-proto": "https",
       },
       maxRedirects: 0,
     });
     await route.fulfill({ response });
   });
   
   for (const path of paths) {
     const response = await page.goto(`http://${ip}${path}`, {
       waitUntil: "networkidle",
     });
     const result = await new AxeBuilder({ page }).analyze();
     const nodes = result.violations.reduce(
       (sum, item) => sum + item.nodes.length,
       0,
     );
     console.log(`${response.status()} ${path} violations=${nodes}`);
     for (const item of result.violations) {
       for (const node of item.nodes) {
         console.log(`  ${item.impact} ${item.id} ${node.target.join(" ")}`);
       }
     }
   }
   await browser.close();

A violation is a failed check. “Incomplete” means axe could not decide, often because of a gradient or an overlap. Incomplete results are neither passes nor failures. The gate is zero critical and zero serious violations on each key template. The container above is the scanner. Playwright and axe are not installed on the host.

Avoid

Danger

A mid-scale brand colour as small text on white. A pair near 2:1 fails. It is not a near miss.

Placeholder text under 4.5:1.

An input or select with no label and no aria-label.

Two h1 elements on one page, or a heading level fixed inside a shared partial.

aria-controls pointing at the control’s own container.

aria-label on a div that has no role.