Accessibility

Note
This page provides accessibility guidance, and is not a catch-all for all web accessibility situations. Seek out additional resources and/or consult with accessibility professionals to ensure web accessibility standards are met and best practices are implemented

Calcite Components leverage the W3C Accessibility Standards to ensure the applications and experiences you create are usable by a wide range of audiences.

While Calcite Design System is created with accessibility in mind, there are additional steps you can take to ensure a diverse audience can navigate, understand, and use the solutions you build.

Designing for individuals

A product of the W3C Accessibility Standards are the Web Content Accessibility Guidelines (WCAG), an internationally agreed upon set of guidelines established to ensure web experiences are usable by a wide range of audiences. Some considerations in designing for individuals include:

On the autism spectrum

Use succinct text.
Do use simple sentences and bullets.
Avoid large blocks of text.
Avoid creating a wall of text.

Who use screen readers

Write descriptive links, such as license details.
Do write descriptive links and headings.
Avoid using vague links, such as learn more.
Avoid writing vague links and headings.

Who have low vision

A user profile that contains a green checkmark.
Do use a combination of color, shapes, and text.
A user profile that is contained in a green circle.
Avoid using only color to convey meaning or status.

With physical or motor difficulties

A radio button that has ample spacing around the component.
Do make large clickable actions.
A radio button that must be selected within the component.
Avoid demanding precision.

Who are deaf or hard of hearing

A video containing subtitles to the supporting audio feedback.
Do use subtitles or provide transcripts for video.
A speaker emitting sound.
Avoid placing content in audio or video formats only.

With dyslexia

A user prompt with relevant information.
Do provide reminders and prompts.
Two gears
Avoid forcing people to remember things from previous actions and/or places.

Color

Avoid relying on color alone to communicate information, which can create barriers for colorblind and low vision users. To ensure your content can be interpreted by a larger audience it is recommended to:

  • Use a combination of color, shapes, patterns, and text to provide additional visual cues
  • Provide a text alternative for complex maps, charts, and graphics

Consider color as a means to enhance your content. Color is an element of visual communication, which supports design, identity, and usability.

For instance, to relay context of an invalid user entered value in Input, use color and an accompanying Input Message.

High contrast

Calcite supports the forced-colors CSS media feature. When Windows high contrast mode is turned on, small changes have been incorporated across components to provide additional contrast.

Animation

Calcite also supports the prefers-reduced-motion CSS media feature, where components will minimize non-essential motion when animations are disabled on the operating system or browser.

When designing an application, consider animation use across the interface to support individuals with vestibular motion disorders. Where animations can not be controlled, animations can impact and impair a user's experience.

When animations do not provide additional context or meaning, the best approach is to remove animation, and when animation provides additional context and meaning, consider reducing motion, while still conveying its meaning. For instance, Loader's animation is greatly reduced to depict something is loading visually, but at a reduced speed.

For animation considerations in interactive maps, explore reduced motion with ArcGIS Maps SDK for JavaScript.

Content

The page's reading order should have a logical structure. To check the reading order, follow the focus commands using the Tab key to step forward and the Shift and Tab keys to step back. The order should have the same flow as displayed visually, particularly with forms and search dialogs.

Content on the page should be clear and concise using plain language, without any use of jargon or undefined acronyms. Line length, either too short or too long, can be confusing to both sighted and non-sighted users. Ensure text content is straightforward, yet distinguishable.

Language

You must set a language on your application so users can read and interpret the content. Setting the language is vital for assistive technologies to access the page contents.

Set the language on the html tag so it can be interpreted throughout the application. If additional languages are needed throughout the page, you can define them as needed, and in some cases, on individual components.

Use dark colors for code blocksCopy
1
<html lang="en">

Headings

To facilitate navigation and understanding of overall document structure, use heading elements that are properly ordered or nested (h1, h2, h3, h4, h5, and h6). Heading elements allow user agents to automatically identify section headings.

For example, if the page includes h1 and h2 tags, when designing a calcite-modal you could use a h2 or h3 tag in the modal's title:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
<!-- If h1 and h2 tags are present, the calcite-modal header could use a h2 or h3 tag -->
<calcite-modal aria-labelledby="modal-title">
    <h3 slot="header" id="modal-title">Modal title</h3>
    <div slot="content">Modal content</div>
    <calcite-button slot="secondary" width="full" appearance="outline">Cancel</calcite-button>
    <calcite-button slot="primary" width="full">Save</calcite-button>
</calcite-modal>

In the same scenario, you should not assign a h4, or higher tag to the calcite-modal title, as the page would not have a designated h3 tag established. The skipped header makes it seem like the user has missed hidden content, which, in effect, creates a usability problem.

Keyboard operability

Similar to heading elements, content should have the same functional and visual order using HTML. When adding multiple elements throughout the page, ensure the HTML matches with the intent.

For example, to ensure content residing in the calcite-switch is accessed by keyboard and visual users in the same hierarchy, the HTML should reflect the same order. First by declaring the calcite-label, next the calcite-switch, and finally the viewDiv.

Use dark colors for code blocksCopy
1
2
3
4
5
<calcite-label layout="inline">Dark mode:
  Off <calcite-switch></calcite-switch> On
</calcite-label>

<div id="viewDiv"></div>

Focus

Keyboard focus refers to the element receiving keyboard input. Exactly one element is able to have focus at a time. In most browsers, users can move focus by pressing the Tab key to step forward and the Shift and Tab keys to step back.

For an otherwise unfocusable element to become focusable, such as a div, it must contain a tabindex attribute. A page's focus order must preserve it's meaning and promote ease of use. Focus order should be logical, and generally follow the visual order of the page.

Note
Do not use tabindex greater than 0 to achieve focus order, doing so can create maintainability problems and unexpected user behavior.

Visible focus

In support of WCAG's success criteria 2.4.7: Focus Visible and 2.4.13: Focus Appearance Calcite provides a visible focus for both mouse and keyboard users. Calcite Components provide a visible focus to ensure more audiences, in particular individuals with low vision and cognitive disabilities, can perceive which element is receiving focus.

No keyboard trap

Support more individuals in ensuring keyboard users do not become trapped in a subset of content that can be exited using a mouse or pointing device in support of Success Criterion 2.1.2: No Keyboard Trap.

The exception is with Dialog, where content is intended for focused interactions. Upon opening, the component's focus will be contained within the component until dismissed or closed. Learn more on Dialog's accessibility.

Alternative text (Alt text)

When adding images to content, leverage alt text to provide a description to the image presented. Be succinct, while also descriptive, to provide context to non-visual users.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
<calcite-card>
    <span slot="heading">Grizzly bears</span>
    <span slot="description">Alaska</span>
    <img src="grizzly-bear.png"
      alt="A grizzly bear captures a salmon mid-flight during Alaska's salmon run,
      an annual return of millions of salmon from the ocean to mountain streams.">
    <div slot="footer-start">
        <calcite-button icon-end="plus">Learn more about bears</calcite-button>
    </div>
</calcite-card>

Forms and labels

When working with forms for readability and to support assistive technologies, you must add labels explicitly to associate text with form elements. Calcite has implemented calcite-label to add labels to form elements. For example:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
</style>

<body>
  <form>
    <fieldset>
      <legend>Report a Monarch Butterfly Sighting</legend>
      <calcite-label>What is your name?
        <calcite-input type="text" placeholder="John Muir"></calcite-input>
      </calcite-label>
      <calcite-label>When did you encounter a Monarch Butterfly?
        <calcite-input-date-picker id="date-picker"></calcite-input-date-picker>
      </calcite-label>
    </fieldset>

Grouping form controls

Grouping within a form is important to provide context, so the form can be understood and submitted successfully. For form submission considerations, explore Core concepts.

The fieldset and legend elements provide grouping for a form control, and it's caption respectively. When designing control-based components in a form, such as calcite-radio-button-group, the fieldset and legend form control elements should accompany the component.

For design consistency, add Calcite Design System Colors and Typography to the form control elements. For instance:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

<body>
  <!-- Grouping and caption for calcite-radio-button-group with form control elements -->
  <fieldset>
    <legend>Have you ever encountered a Monarch Butterfly?</legend>
    <calcite-radio-button-group>
      <calcite-label layout="inline"> <calcite-radio-button value="yes"></calcite-radio-button>Yes </calcite-label>
      <calcite-label layout="inline"> <calcite-radio-button value="maybe"></calcite-radio-button>Maybe </calcite-label>
      <calcite-label layout="inline"> <calcite-radio-button value="no"></calcite-radio-button>Not yet </calcite-label>

Checklist

Your solutions should be inclusive, and accessible to as many people as possible. The checklist below helps identify potential accessibility issues to keep in mind while designing and developing with Calcite Design System.

Note
Completing the checklist does not guarantee the solutions you build are accessible. However, addressing issues from the checklist will improve the experience for a larger audience.

Content

Information should not depend on color, sound, shape, size, or visual location Text and background color should have sufficient contrast Links should be descriptive and provide intent Use descriptive section headings Forms contain descriptive labels Forms have helpful error and verification messages Labels accompany their associated form fields Content does not lose context when zoomed or enlarged Site should not time out unexpectedly Content is understandable with no styles enabled Web page size should not exceed 500k

Keyboard and assistive technology

Support keyboard navigation Avoid mouse only interactions Focus states should be visible for keyboard users Allow keyboard users to skip navigation Users should be able to navigate content using a screen reader

Multimedia and data visualization

Images should have meaningful alternative text, or be intentionally marked as decorative Decorative images should not be read to screen readers Multimedia should have alternative ways to be consumed Table data can be accessed by non-sighted users Make data available for graphs, charts, maps, SVGs, etc. through assistive technology Content that moves automatically has the ability to be paused Limit or remove any flashing elements Ensure audio and video is not played automatically

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.