Darek Kay's picture
Darek Kay
Solving web mysteries
Home Blog Projects

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:

Resources

Collections

General

Motivation

  • A site is accessible when its content is available, and its functionality can be operated, by literally anyone.
  • Disability accommodations often benefit everyone, not just disabled people. Think about wheelchair ramps: parents pushing a stroller, someone walking a bicycle, or someone towing a heavy load on wheels.

Best practices

Libraries

Tools / Audit

Stories

Language

Focus indicator

  • Consider different implementation techniques.
  • The focus indicator must have a contrast ratio of 3:1 against its adjacent elements, or be at least 2px wide. (WCAG 2.2)
  • The focus indicator must have a 3:1 (AA) / 4.5:1 (AAA) contrast ratio between its focused and unfocused states. (WCAG 2.2)
  • 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

Fonts

WCAG / WAI-ARIA

Screen reader

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.
    • Screen reader's punctuation announcement depends on its order, e.g. NVDA announces question marks only at the end of a sentence by default.
  • 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>

NVDA

  • Settings:
    • ☑ Tools → Speech viewer
      • ☑ Show Speech Viewer on Startup
    • ☑ Preferences → Keyboard → Select NVDA Modifier Keys → caps lock
  • Addons:
  • Notes:
    • 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

Dragon

Elements and Widgets

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

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

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

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)

Dialog / Modal

  • 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:
  • There was a Chrome bug, making it impossible to adjust the fieldset display value.

There are some rules regarding the <footer> element:

  1. The HTML footer element defines a contentinfo landmark when its context is the body element.
  2. The HTML footer element is not considered a contentinfo landmark when it is a 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

  • A H1 doesn't have to come first (example).
  • These are no WCAG violations, but should still be avoided:
    • Missing or more than one <h1>.
    • Skipping heading levels.
    • Multiple headings with the same text.

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

Inputs

<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>

Buttons

  • There is a difference when pressing Enter or Space with buttons:
    • A native <button> fires on key down when that key is Enter. If you hold down the Enter key, it continues to fire for as long you hold Enter (or something crashes).
    • A native <button> fires on key up when that key is Space. If you do not release the Space, and also press Tab to move away from the control, the control will not fire.

SVGs

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

Tables

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

Tooltips

Video Player

Accessibility Notes
Darek Kay