Accessibility

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

Principles

The Web Content Accessibility Guidelines (WCAG) are internationally agreed upon standards established to help create accessible experiences.

The four principles of web accessibility include:

Hierarchy

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:

1
2
3
4
5
6
7
<!-- If h1 and h2 tags are present, the 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.

1
2
3
4
5
6
7
<!-- Switch with label -->
<calcite-label layout="inline">Dark mode:
  Off <calcite-switch></calcite-switch> On
</calcite-label>

<!-- Map view -->
<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.

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 seen 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 concise, yet distinguishable.

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.

1
2
3
4
5
6
7
8
9
<!-- Alt text example -->
<calcite-card>
    <span slot="title">Grizzly bears</span>
    <span slot="subtitle">Alaska</span>
    <img src="grizzly-bear.png" alt="Close-up of a grizzly bear's face">
    <div slot="footer-leading">
        <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 assist non-visual users, you must add labels explicitly to associate text with form elements. Calcite has implemented calcite-label to add labels to form elements. For example:

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
<!-- Accessible form example -->
<form id="form">
  <fieldset>
    <legend>Questionnaire</legend>
    <ol>
      <li>
          <!-- Calcite input with label -->
          <calcite-label>Your name
            <calcite-input type="text" placeholder="John Doe"></calcite-input>
          </calcite-label>
      </li>
      <li>
        <!-- Calcite select with label -->
        <calcite-label>Where did you hear about Calcite components?
            <calcite-select>
            <!-- Calcite options with labels -->
            <calcite-option label="Please select&hellip;"></calcite-option>
            <calcite-option label="Esri DevSummit"></calcite-option>
            <calcite-option label="Search engine"></calcite-option>
            <calcite-option label="Social media"></calcite-option>
            <calcite-option label="A little bird told me"></calcite-option>
            </calcite-select>
        </calcite-label>
      </li>
      <li>
        <!-- Calcite combobox with label -->
        <calcite-label>What is your favourite component(s)?
          <calcite-combobox id="combobox" placeholder="Select favorites&hellip;" max-items="6"></calcite-combobox>
        </calcite-label>
      </li>
    </ol>
  </fieldset>
</form>