Accessibility Notes

My notes for making the web more inclusive. Don't follow this guide blindly. Read the references to learn more about certain rules.

Check out my general best practices for building better applications.

This page is a continuous work in progress.

Where to start?

Accessibility fundamentals are covered in the Web Fundamentals Guide (Google) and the Web Accessibility Course (Udacity/Google). Both resources are free.

To evaluate the accessibility of a web page, try out the following tools:

Chrome/Firefox browser extension: WAVE
Command line: evaluatory

Resources

Collections

General

Best practices

Provide a correct lang attribute.
Ensure that interactive controls have at least a 44x44 pixels target click size.

Libraries

Accessible, responsive canvas.
a11y-dialog - Accessible JS modal dialog.
Comica11y - accessible comics.

Tools / Audit

Accessibility tools audit — An example page to test the effectiveness of accessibility tools.
There are multiple issues with AccessiBe and other overlays.
Building the most inaccessible site possible with a perfect Lighthouse score.

Stories

The WebAIM Million - An annual accessibility analysis of the top 1,000,000 home pages.
Losing sight.
I'm a software engineer going blind, how should I prepare?.
A blog where the author describes their way to become certified in WAS and CPACC.

Focus indicator

Don't disable outline, master it instead.
It is not required that hover as a state is differentiated from the default (and presumably all other) states.
Adjusting the flex order does not change the focus order.
Provide a fallback for Windows High Contrast mode when using a box-shadow focus indicator.
A keyboard-only focus ring has pros and cons, but it is technically possible using :focus-visible. Progressive enhancement handles older browsers.

Colors / Contrast Ratio

Labels

Alt-Texts — The Ultimate Guide.
- Add punctuation to your alt text.
There are limitations of aria-label, aria-labelledby and aria-describedby. It's complicated.
Google Translate does not translate aria-label labels.
HTML for vs wrapping label.

Fonts

There's no evidence that typefaces designed to help dyslexics have any effect.
Accessible font types.
Atkinson Hyperlegible Font.

WCAG / WAI-ARIA

WCAG-compliant website showcase
Rules for using ARIA.
An in-depth guide to ARIA roles.
A password role is under discussion.
The role="none" is not supported in IE11.
Do not put aria-hidden on focusable elements.

NVDA Keyboard Shortcuts
User survey 2019 (browser/screen reader usage)
Do not use screen reader detection.
Screen reader icon (public domain):

Support

Announcement

A screen reader may announce things differently than displayed in the text viewer. Pay attention to times, dates, currency, punctuation, special characters, emoji, math symbols, common (and uncommon) abbreviations & acronyms.
Minus the minus - A PSA about screen readers and negative numbers.
- NVDA has fixed a related issue.
- Talkback doesn't recognize the - character correctly.
Acronyms can usually be left as-is.
NVDA announces values differently between divs and spans.
NVDA does not announce emphasis elements (like em or strong).
Improve the announcement of phone numbers:

<a href="tel:703555121" aria-label="7 0 3. 5 5 5. 1 2 1.">(703) 555-121</a>

::before and ::after content is screen reader accessible (except IE11).
CSS generated content is not fully accessible.
- A live region will announce changes coming from a CSS counter.
- Defining an alternative text for CSS content.
How the display properties affect <table>, <ul>, <ol>, <dl>, <h#>, <button>.
German gender characters are not excluding screen reader users.

NVDA

NVDA does not focus inline links in browse mode, unless the link appears at the start of a line.

VoiceOver

Shortcuts:
- Start: Cmd + F5
Settings:
- ☐ Verbosity → Hints → Speak instructions for using the item in the VoiceOver cursor
- ☑ Sound → Mute sound effects

Elements and Widgets

HTML: The Inaccessible Parts.
Avoid strikethrough element, as the semantics are not announced by screen readers.

Date Picker

Something I see (...) is the frustration with date fields that are anything other than a plain text field for well-known dates (like birthdays).

Definition Lists

Axe Rule

<dl>
  <dt>Coffee</dt>
  <dd>Black hot drink</dd>

  <dt>Milk</dt>
  <dd>White cold drink</dd>
</dl>

Wrappings divs are allowed.
NVDA does not expose definition lists correctly, but:

It's worth noting that a definition list is the correct way to mark up a list of paired items. Changing markup patterns to satisfy the vagaries of specific assistive technologies tends to be a slippery slope. (source)

There is no fixed rule where the focus should be moved to after opening a modal. A headline or the dialog itself are two good possibilities. There is an ongoing discussion about the default behavior for the HTML dialog element.

Fieldset

A legend has to be a direct child of a fieldset. A screen reader might not announce the label if the markup is malformed (e.g. NVDA). Solutions:
- Use role="group" + aria-labelledby instead.
- Use a duplicate label
There was a Chrome bug, making it impossible to adjust the fieldset display value.

There are some rules regarding the <footer> element:

The HTML footer element defines a contentinfo landmark when its context is the body element.
The HTML footer element is not considered a contentinfo landmark when it is descendant of any of following elements: article, aside, main, nav, section

A contentinfo landmark role is used to identify information repeated at the end of every page of a website, hence a page should not have more than one contentinfo landmark.

Headline

Use a single H1 per page. It doesn't have to come first, though (example).
Don't skip headline levels.

Images

Decorational images:

We tried to outsmart screen readers by letting them skip descriptive images. This turned out to be really unhelpful. Users that are not fully blind will still see an image and when the screen reader skips these images, users will assume they missed out on information. Solution: let the screen reader tell the users it’s a descriptive image. Or even better, write a descriptive alt-text for images. source

Background images are mostly ignored in Windows High Contrast mode.

Inputs

Prefer type="search" for search inputs, even though it currently offers little benefit.

Links

<div hidden>
  <span id="new-window-0">Opens in a new window</span>
  <span id="new-window-1">Opens an external site</span>
  <span id="new-window-2">Opens an external site in a new window</span>
</div>

<a
  href="https://example.com"
  target="_blank"
  rel="noopener"
  aria-describedby="new-window-0"
>
  My site
</a>

Download links:
- Use <a>, not a <button>.
- Provide media type and file size visually readable.
The trouble with mailto email links and what to do instead.

SVGs

Creating accessible SVGs
- Update 2021

<svg role="img">
  <title>Lightbulb moment!</title>
  <path d="..." />
</svg>

Tables

Include a table caption:

<table>
  <caption>
    Populations of cities
  </caption>
  <thead>
    ...
  </thead>
  <tbody>
    ...
  </tbody>
</table>

Tooltips

Accessible tooltips

Video Player

Why videos on GOV.UK use the YouTube video player.
Don't rely on YouTube transcripts.