Acme Accessibility: Overview

Get a lay of the accessible landscape at Acme

Simulating Accessibility

To see what it’s like to use as an accessibility user, try out each of these sections as part of your onboarding. Try not to “cheat”… if you can! 😉

Keyboard Navigation

Some users don’t have or use a mouse. Try navigating through the site using tab on your keyboard and triggering elements with enter, space, or up/down.


Some users rely on narration software to dictate what’s on their screen. You can simulate being that kind of user with VoiceOver on Mac or Narrator on Windows.

Preventative Measures

It’s estimated that static and dynamic analysis can catch at most 30% of violations.

Static Analysis

ESLint rules are your friends! eslint-plugin-jsx-a11y helps flag some known accessibility issues.

Rules all have extensive documentation with linked reference in that repository.

Do not add new /* eslint-disable */ directives for a11y rules.

Existing /* eslint-disable */ directives are legacy; please clean them up!

Dynamic Analysis

Most browsers come with some level of accessibility scanning in their developer tools. We recommend you use the more powerful and better-featured aXe Browser Extension.

aXe is a tool that scans a webpage for known accessibility failures at runtime. Use it when developing site UI to catch basic violations.

Acceptance Tests

aXe can be run during TestCafe to fail an acceptance test if violations are detected.

Import the axeCheck function and await for its result on a t test:

import axeCheck from 'axe-testcafe'; import { config, endpoints } from '../../config'; import { runAxeChecks } from '../../helpers/runAxeChecks'; fixture`About`.page`${config.baseURL}${endpoints.about}`; test('has no accessibility complaints when loaded', async t => { await waitForReact(); const { result, report } = await runAxeChecks(t); await t.expect(result).ok(report); });

When developing new site pages, always include accessibility tests.

User Testing

Again, static and dynamic analysis combined typically capture barely a third of all accessibility issues. Before releasing a new page to users, you should request an accessibility audit.

Common Design Accessibility Mistakes

Color Contrast

All text must have enough color contrast against its background. There must be a 4.5:1 contrast ratio for ‘body’ text and a 3.0:1 ratio for ‘heading’ text.

See this tool for color checking and details:

Timed Disappearing

Animated entrances and exists on the page are fine as long as users are not required to act within a particular time frame.

For example, if you add a small popup within the page to indicate some notification has occurred, it should remain on the page until dismissed by the user — not for only a limited time.

Common Engineering Accessibility Mistakes

Focus Management

Built-in HTML elements come with semantic meaning already. Don’t attach click listeners to plain <div>s; instead, use <input>s or <button>s.


Similarly, <h1> - <h6> headings have semantic meaning: they imply (sub-)sections of the page. Don’t use headings unless your text is actually a “heading”!

A page can only have one h1, and it should come before other page content. Think of an outline of notes.

Note: Rarely, a hidden h1 tag might be needed. See: /HiddenH1/index (link)

Image Alts

All images on the site fall into one of two categories:


Images that add meaning to the page, such as icons, profile photos, and diagrams.

These need alt text on the HTML element so that screenreaders can narrate them. See existing images on the site for examples of proper alt text.


Images that don’t add meaning to the page, such as background photos and callout pointers.

These can have alt="" so that screenreaders don’t narrate them.

Unrelated tip: add user-select: none; in the SCSS styles for background images.

These tips apply to Contentful image titles and descriptions as well!