Accessibility

This is for:

Developer

Coveo designed the Atomic library with accessibility in mind. It adheres to the Accessible Rich Internet Applications (ARIA) standards and follows the Web Content Accessibility Guidelines (WCAG).

While developing Atomic, we’ve tried to make the user experience with screen readers as comfortable and consistent as possible. We’ve tested it with the following screen readers:

However, Atomic is a customizable library which can’t control every element of a web page. Consequently, it can only ensure that some parts of the user experience adhere to the listed accessibility standards. This article explains how you can improve the accessibility of your own search interfaces when using Atomic.

Improve contrast ratios

We recommend that the color contrast ratios in your interface conform to WCAG Level AA (see Success Criterion 1.4.3: Contrast (Minimum)).

If you’re using the theme that’s included with Atomic (coveo.css), you can ensure that Atomic conforms to accessibility standards by replacing it with the accessibility theme (accessible.css).

If you’re using a custom theme, we recommend that you customize the colors and font sizes in your interface to conform to accessibility standards.

Add headings

According to a survey by WebAIM, 67.7% of respondents were more likely to navigate by headings first when trying to find information in a lengthy webpage. Atomic is a component-based library that lets you divide your search interfaces to suit your needs, so its components don’t include headings. We recommend that you add headings to allow screen reader users to jump between relevant sections of your page.

<body>
  <style>
    .screen-reader-only {
      height: 0;
      margin: 0;
      overflow: hidden;
    }
  </style>
  <atomic-search-interface>
    <h1 class="screen-reader-only">Search</h1>
    <atomic-search-box></atomic-search-box>
    <h1 class="screen-reader-only">Summary</h1>
    <atomic-query-summary></atomic-query-summary>
    <h1 class="screen-reader-only">Facets</h1>
    <atomic-facet-manager>
      <h2 class="screen-reader-only">Brand</h2>
      <atomic-facet field="ec_brand" label="Brand"></atomic-facet>
      <h2 class="screen-reader-only">Rating</h2>
      <atomic-rating-facet field="ec_rating" label="Rating"></atomic-rating-facet>
    </atomic-facet-manager>
    <h1 class="screen-reader-only">Results</h1>
    <atomic-result-list display="grid">
      <atomic-result-template>
        <template>
          <atomic-result-section-title>
            <h2><atomic-result-link></atomic-result-link></h2>
          </atomic-result-section-title>
        </template>
      </atomic-result-template>
    </atomic-result-list>
  </atomic-search-interface>
</body>

Use atomic-aria-live

To notify screen reader users of some changes (for example, the result list being updated), a webpage needs an ARIA live region. By default, the search interface will define one, but due to some limitations when aria-live is inside the search interface, it may behave inconsistently on some screen readers.

We recommend that you add an atomic-aria-live element outside of the search interface, so every Atomic component that needs it will automatically detect it.

We don’t recommend that you dynamically add or remove this element from the page, because it could lead to screen readers losing track of it. Instead, we recommend that you include atomic-aria-live during the initial rendering of the page.

<body>
  <atomic-aria-live></atomic-aria-live>
  ...
  <atomic-search-interface>
    ...
  </atomic-search-interface>
</body>

Improve result accessibility

Since results are highly customizable, the relevant components offer limited out-of-the-box accessibility support. However, we recommend the following to help you provide an accessible experience for your users.

Reorder result sections

Note

This is only relevant if you use result sections in your result template.

While the visual order of sections is independent of the order in which they were defined in the template, screen readers will try reading sections in the order in which they’re defined. As such, we recommend that you order result sections from most important to least important, with the title section being the most important. This order is highly subjective, so we recommend that you take inspiration from other accessible search pages with a purpose similar to yours.

<atomic-result-section-title>...</atomic-result-section-title>
<atomic-result-section-emphasized>...</atomic-result-section-emphasized>
<atomic-result-section-title-metadata>...</atomic-result-section-title-metadata>
<atomic-result-section-badges>...</atomic-result-section-badges>
<atomic-result-section-visual>...</atomic-result-section-visual>
<atomic-result-section-excerpt>...</atomic-result-section-excerpt>
<atomic-result-section-bottom-metadata>...</atomic-result-section-bottom-metadata>

Hide the thumbnail

Your results may include a thumbnail as well as a detailed title. If your title accurately describes the content which is depicted in a thumbnail, it means that the thumbnail doesn’t contain additional information for screen readers.

In such a case, the thumbnail would slow down navigation for screen reader users, so we recommend that you hide the thumbnail from screen readers.

Achieve this by setting its aria-hidden property to true.

<atomic-result-image
  field="ec_images"
  aria-hidden="true"
></atomic-result-image>

Add roles

We recommend that you add semantic roles to certain result components to better communicate to screen readers what they represent in your particular template. However, be aware that adding a role to a component overwrites its original role and that screen readers may expect some roles to have specific children or support specific keyboard shortcuts.

In general, we recommend making the following adjustments:

  • Add the role="grid" property to the element containing all your fields and:

    • Wrap each field label-value pair in an element with the role="row" property.

    • Add the role="rowheader" property to each field label.

    • Add the role="cell" property to each field value.

    <atomic-result-section-bottom-metadata>
  <atomic-result-fields-list role="grid">
    <div role="row">
      <span role="rowheader">Priority:&nbsp;</span>
      <atomic-result-text field="priority" role="cell"></atomic-result-text>
    </div>
    <atomic-field-condition if-defined="deadline" role="row">
      <span role="rowheader">Deadline:&nbsp;</span>
      <atomic-result-date field="deadline" role="cell"></atomic-result-date>
    </atomic-field-condition>
    ...
  </atomic-result-fields-list>
</atomic-result-section-bottom-metadata>

  • Add the role="note" property to atomic-result-badge components.

    <atomic-result-badge field="special" role="note"></atomic-result-badge>