Accessibility

Dimagi’s product design team firmly believes that web and software experiences should be accessible for everyone, regardless of abilities or impairments.

Overview

Accessible products give every user the same benefits regardless of ability and can adapt to any user in any context. Disabilities can be situational (an end user with typical vision may struggle to view their screen in a bright or sunny environment), temporary (a person with a broken wrist may not be able to type in HQ but will regain ability when healed), and long-lasting (barriers from birth, an illness, disease, accident, or developed over age; some may not consider themselves to have disabilities even if they experience functional limitations). We design and build products for everyone.

"Everyone" includes

18% of adults with vision impairment (source)
8.6% of adults with hearing trouble (16.8% of U.S. adults!) (source and source)
15% of adults with physical functioning difficulty (source and source)
4.4% of adults with cognitive disabilities (source)

Consider the following barriers when designing and coding

Blindness (may use screen reader, lack access to mouse, rely on text over visual information
Low-Vision (may use screen readers/magnifiers, high contrast or monochrome displays; maximize readability and visual clarity; try NoCoffee plugin
Color-blindness (may not be able to differentiate between some colors; test designs in a color-blind simulator)
Deaf and Hard-of-Hearing (may rely on captioning and alternative representations of audio
Physical Disabilities (may rely on keyboards, trackballs, voice recognition or assistive tech, may lack mouse access
Cognitive Disabilities (may have limited working memory, problem solving, attention, reading/linguistic/visual comprehension, sensitivity to flashing content; try to design linearly and focus on heuristics that have to do with cognitive load and memory)

A11y check

AA CONTRAST 4.86:1 AAA Contrast 7.01:1
AAA Contrast 12.05:1 AAA Contrast 11.07:1

Quick ways to test web accessibility

Keyboard Navigation: Test if modified code is navigable by keyboard, an effective way to ensure page navigability and screen reader visibility. More information and tips here.
Explore the Accessibility Tree: Use Chrome DevTools' accessibility feature to view the accessibility tree of a page under development, understanding how page elements are included, visible, and organized. This is especially helpful for understanding what a specific element is, how it’s labeled, and how it’s defined in relation to other elements on the screen.
Use a Screen Reader: Free options like VoiceOver for Mac, ORCA for Linux, and NVDA for Windows can assist in testing accessibility. Warning: different screen readers can read the same webpage differently so using one is a good launching point but it is also recommended to utilize different screen readers in final testing.
Check color contrast:We aim for AA compliant color contrast. You can check color contrast in tools such as https://webaim.org/resources/contrastchecker/.
WAVE Browser Extension: WAVE which identifies Web Content Accessibility Guideline (WCAG) errors
Keep in mind that this list is not exhaustive and covers only a portion of what makes a site accessible to all users. Ensuring accessibility is an ongoing commitment to creating inclusive digital experiences for everyone.

Focusability, Tabbability, and Visibility

tabindex Attribute

The tabindex attribute specifies the tab order of an element and determines whether an element can receive keyboard focus. Here are some scenarios where you might use tabindex:

Focusable but Not Natively Focusable Elements: Some elements like <div> or <span> are not natively focusable, but you might want them to receive focus for user interaction. In such cases, you can add tabindex="0" to make them focusable. Note: we avoid using custom focus order using tab index with values above 0. Instead, make sure DOM elements are ordered correctly for navigability, then modify visual positioning with CSS if needed.
Remove Focusability: to explicitly remove an item set tabindex="-1"
Dynamic Focus Control: If you have dynamically generated or hidden elements that need to become focusable under certain conditions, you can dynamically add or remove the tabindex attribute.

aria-hidden Attribute

The aria-hidden attribute indicates whether an element is visible or hidden to assistive technologies. It does not affect the visual rendering of the page. Here are some scenarios where you might use aria-hidden:

Hiding Decorative Elements: If you have decorative or presentational elements that should be hidden from screen readers, you can use aria-hidden="true".
Dynamic Content Updates: When dynamically updating content, you may want to temporarily hide or show certain elements from assistive technologies without altering their visual display.
Modal Dialogs or Popovers: When displaying modal dialogs or popovers, you may want to hide the underlying content from screen readers to prevent confusion.

When to Use Each

Use tabindex when you need to remove or add tab focusability to an element.

Use aria-hidden when you need to hide elements from assistive technologies while keeping them visible on the page or dynamically toggle their visibility.

Common Mistakes (and how to fix them)

Using Non-Semantic HTML Elements for Interactive Components
Error: Using <div> or <span> elements for interactive components like buttons or links instead of using native HTML elements.
```

```
```
<div onclick="handleClick()">Click me</div>
```
```

```
```
<button onclick="handleClick()">Click me</button>
```
Fix: Replace non-semantic elements with appropriate semantic HTML elements like <button> for buttons and <a> for links. This fix also ensure that by creating interactive elements that cannot be accessed or operated using the keyboard.
Missing or Incomplete ARIA (Accessible Rich Internet Applications) Attributes
Error: Failing to provide necessary ARIA attributes or providing incomplete information, which can result in screen readers not conveying the correct information to users.
```

```
```
<button>×</button>
```
```

```
```
<button aria-label="Close">×</button>
```
Fix: Include essential ARIA attributes like aria-label or aria-labelledby to provide meaningful information to assistive technologies when symbols or other visual information convey information that is otherwise not present.

Inconsistent Use of ARIA Attributes

Error: Inconsistently using ARIA attributes across similar UI components, leading to confusion for users relying on assistive technologies.

<!-- Incorrect: Inconsistent use of aria-hidden -->

<div id="modal1" aria-hidden="true">Modal 1 Content</div>

<div id="modal2">Modal 2 Content</div>

<!-- Correct: Consistent use of aria-hidden -->

<div id="modal1" aria-hidden="true">Modal 1 Content</div>

<div id="modal2" aria-hidden="true">Modal 2 Content</div>

Overusing ARIA attributes
Error: Using ARIA attributes unnecessarily can clutter the code and potentially confuse users or interfere with native accessibility features. This is often a crutch needed when not using semantic HTML (Semantic means "relating to meaning". Writing semantic HTML means using HTML elements to structure content based on each element's meaning, not its appearance.)
```

```
```
<div role="button" tabindex="0" aria-label="Click me" aria-describedby="button-description">Click me</div>
```
```

```
```
<button>Click me</button>
```
Fix: Use ARIA attributes only when necessary to supplement or enhance the accessibility of UI components, avoiding unnecessary or redundant attributes.

By avoiding these common coding errors and following best practices for ARIA implementation, you can ensure that your front-end code adheres to ARIA guidelines and provides a more accessible user experience for all users.