Accessibility

Accessibility is important for users who use screen readers or rely on keyboard-only functionality to ensure they have an equivalent experience to sighted mouse users.

This page contains guidelines we should follow.

Quick summary

Since no ARIA is better than bad ARIA, review the following recommendations before using aria-*, role, and tabindex. Use semantic HTML, which has accessibility semantics baked in, and ideally test with relevant combinations of screen readers and browsers.

In WebAIM’s accessibility analysis of the top million home pages, they found that “ARIA correlated to higher detectable errors”. It is likely that misuse of ARIA is a big cause of increased errors, so when in doubt don’t use aria-*, role, and tabindex and stick with semantic HTML.

Enable keyboard navigation on macOS

By default, macOS limits the tab key to Text boxes and lists only. To enable full keyboard navigation:

  1. Open System Preferences.
  2. Select Keyboard.
  3. Open the Shortcuts tab.
  4. Enable the setting Use keyboard navigation to move focus between controls.

You can read more about enabling browser-specific keyboard navigation on a11yproject.

Quick checklist

Provide a good document outline

Headings are the primary mechanism used by screen reader users to navigate content. Therefore, the structure of headings on a page should make sense, like a good table of contents. We should ensure that:

  • There is only one h1 element on the page.
  • Heading levels are not skipped.
  • Heading levels are nested correctly.

Provide accessible names for screen readers

To provide markup with accessible names, ensure every:

  • input has an associated label.
  • button and link have visible text, or aria-label when there is no visible text, such as for an icon button with no content.
  • image has an alt attribute.
  • fieldset has legend as its first child.
  • figure has figcaption as its first child.
  • table has caption as its first child.

Groups of checkboxes and radio inputs should be grouped together in a fieldset with a legend. legend gives the group of checkboxes and radio inputs a label.

If the label, child text, or child element is not visually desired, use .gl-sr-only to hide the element from everything but screen readers.

Examples of providing accessible names

The following subsections contain examples of markup that render HTML elements with accessible names.

Note that when using GlFormGroup:

  • Passing only a label prop renders a fieldset with a legend containing the label value.
  • Passing both a label and a label-for prop renders a label that points to the form input with the same label-for ID.

Text inputs with accessible names

When using GlFormGroup, the label prop alone does not give the input an accessible name. The label-for prop must also be provided to give the input an accessible name.

Text input examples:

<!-- Input with label -->
<gl-form-group :label="__('Issue title')" label-for="issue-title">
  <gl-form-input id="issue-title" v-model="title" />
</gl-form-group>

<!-- Input with hidden label -->
<gl-form-group :label="__('Issue title')" label-for="issue-title" label-sr-only>
  <gl-form-input id="issue-title" v-model="title" />
</gl-form-group>

textarea examples:

<!-- textarea with label -->
<gl-form-group :label="__('Issue description')" label-for="issue-description">
  <gl-form-textarea id="issue-description" v-model="description" />
</gl-form-group>

<!-- textarea with hidden label -->
<gl-form-group :label="__('Issue description')" label-for="issue-description" label-sr-only>
  <gl-form-textarea id="issue-description" v-model="description" />
</gl-form-group>

Alternatively, you can use a plain label element:

<!-- Input with label using `label` -->
<label for="issue-title">{{ __('Issue title') }}</label>
<gl-form-input id="issue-title" v-model="title" />

<!-- Input with hidden label using `label` -->
<label for="issue-title" class="gl-sr-only">{{ __('Issue title') }}</label>
<gl-form-input id="issue-title" v-model="title" />

Select inputs with accessible names

Select input examples:

<!-- Select input with label -->
<gl-form-group :label="__('Issue status')" label-for="issue-status">
  <gl-form-select id="issue-status" v-model="status" :options="options" />
</gl-form-group>

<!-- Select input with hidden label -->
<gl-form-group :label="__('Issue status')" label-for="issue-status" label-sr-only>
  <gl-form-select id="issue-status" v-model="status" :options="options" />
</gl-form-group>

Checkbox inputs with accessible names

Single checkbox:

<!-- Single checkbox with label -->
<gl-form-checkbox v-model="status" value="task-complete">
  {{ __('Task complete') }}
</gl-form-checkbox>

<!-- Single checkbox with hidden label -->
<gl-form-checkbox v-model="status" value="task-complete">
  <span class="gl-sr-only">{{ __('Task complete') }}</span>
</gl-form-checkbox>

Multiple checkboxes:

<!-- Multiple labeled checkboxes grouped within a fieldset -->
<gl-form-group :label="__('Task list')">
  <gl-form-checkbox value="task-1">{{ __('Task 1') }}</gl-form-checkbox>
  <gl-form-checkbox value="task-2">{{ __('Task 2') }}</gl-form-checkbox>
</gl-form-group>

<!-- Or -->
<gl-form-group :label="__('Task list')">
  <gl-form-checkbox-group v-model="selected" :options="options" />
</gl-form-group>

<!-- Multiple labeled checkboxes grouped within a fieldset with hidden legend -->
<gl-form-group :label="__('Task list')" label-sr-only>
  <gl-form-checkbox value="task-1">{{ __('Task 1') }}</gl-form-checkbox>
  <gl-form-checkbox value="task-2">{{ __('Task 2') }}</gl-form-checkbox>
</gl-form-group>

<!-- Or -->
<gl-form-group :label="__('Task list')" label-sr-only>
  <gl-form-checkbox-group v-model="selected" :options="options" />
</gl-form-group>

Radio inputs with accessible names

Single radio input:

<!-- Single radio with a label -->
<gl-form-radio v-model="status" value="opened">
  {{ __('Opened') }}
</gl-form-radio>

<!-- Single radio with a hidden label -->
<gl-form-radio v-model="status" value="opened">
  <span class="gl-sr-only">{{ __('Opened') }}</span>
</gl-form-radio>

Multiple radio inputs:

<!-- Multiple labeled radio inputs grouped within a fieldset -->
<gl-form-group :label="__('Issue status')">
  <gl-form-radio value="opened">{{ __('Opened') }}</gl-form-radio>
  <gl-form-radio value="closed">{{ __('Closed') }}</gl-form-radio>
</gl-form-group>

<!-- Or -->
<gl-form-group :label="__('Issue status')">
  <gl-form-radio-group v-model="selected" :options="options" />
</gl-form-group>

<!-- Multiple labeled radio inputs grouped within a fieldset with hidden legend -->
<gl-form-group :label="__('Issue status')" label-sr-only>
  <gl-form-radio value="opened">{{ __('Opened') }}</gl-form-radio>
  <gl-form-radio value="closed">{{ __('Closed') }}</gl-form-radio>
</gl-form-group>

<!-- Or -->
<gl-form-group :label="__('Issue status')" label-sr-only>
  <gl-form-radio-group v-model="selected" :options="options" />
</gl-form-group>

File inputs with accessible names

File input examples:

<!-- File input with a label -->
<label for="attach-file">{{ __('Attach a file') }}</label>
<input id="attach-file" type="file" />

<!-- File input with a hidden label -->
<label for="attach-file" class="gl-sr-only">{{ __('Attach a file') }}</label>
<input id="attach-file" type="file" />

GlToggle components with an accessible names

GlToggle examples:

<!-- GlToggle with label -->
<gl-toggle v-model="notifications" :label="__('Notifications')" />

<!-- GlToggle with hidden label -->
<gl-toggle v-model="notifications" :label="__('Notifications')" label-position="hidden" />

GlFormCombobox components with an accessible names

GlFormCombobox examples:

<!-- GlFormCombobox with label -->
<gl-form-combobox :label-text="__('Key')" :token-list="$options.tokenList" />

Images with accessible names

Image examples:

<img :src="imagePath" :alt="__('A description of the image')" />

<!-- SVGs implicitly have a graphics role so if it is semantically an image we should apply `role="img"` -->
<svg role="img" :alt="__('A description of the image')" />

<!-- A decorative image, hidden from screen readers -->
<img :src="imagePath" :alt="" />

Buttons and links should have accessible names that are descriptive enough to be understood in isolation.

<!-- bad -->
<gl-button @click="handleClick">{{ __('Submit') }}</gl-button>

<gl-link :href="url">{{ __('page') }}</gl-link>

<!-- good -->
<gl-button @click="handleClick">{{ __('Submit review') }}</gl-button>

<gl-link :href="url">{{ __("GitLab's accessibility page") }}</gl-link>

Links can be styled like buttons using GlButton.

 <gl-button :href="url">{{ __('Link styled as a button') }}</gl-button>

Role

In general, avoid using role. Use semantic HTML elements that implicitly have a role instead.

BadGood
<div role="button"><button>
<div role="img"><img>
<div role="link"><a>
<div role="header"> <h1> to <h6>
<div role="textbox"> <input> or <textarea>
<div role="article"><article>
<div role="list"> <ol> or <ul>
<div role="listitem"><li>
<div role="table"><table>
<div role="rowgroup"> <thead>, <tbody>, or <tfoot>
<div role="row"><tr>
<div role="columnheader"><th>
<div role="cell"><td>

Support keyboard-only use

Keyboard users rely on focus outlines to understand where they are on the page. Therefore, if an element is interactive you must ensure:

  • It can receive keyboard focus.
  • It has a visible focus state.

Use semantic HTML, such as a (GlLink) and button (GlButton), which provides these behaviours by default.

Keep in mind that:

  • Tab and Shift-Tab should only move between interactive elements, not static content.
  • When you add :hover styles, in most cases you should add :focus styles too so that the styling is applied for both mouse and keyboard users.
  • If you remove an interactive element’s outline, make sure you maintain visual focus state in another way such as with box-shadow.

See the Pajamas Keyboard-only page for more detail.

tabindex

Prefer no tabindex to using tabindex, since:

  • Using semantic HTML such as button (GlButton) implicitly provides tabindex="0".
  • Tabbing order should match the visual reading order and positive tabindexs interfere with this.

Avoid using tabindex="0" to make an element interactive

Use interactive elements instead of div and span tags. For example:

  • If the element should be clickable, use a button (GlButton).
  • If the element should be text editable, use an input or textarea.

Once the markup is semantically complete, use CSS to update it to its desired visual state.

<!-- bad -->
<div role="button" tabindex="0" @click="expand">Expand</div>

<!-- good -->
<gl-button class="gl-p-0!" category="tertiary" @click="expand">Expand</gl-button>

Do not use tabindex="0" on interactive elements

Interactive elements are already tab accessible so adding tabindex is redundant.

<!-- bad -->
<gl-link href="help" tabindex="0">Help</gl-link>
<gl-button tabindex="0">Submit</gl-button>

<!-- good -->
<gl-link href="help">Help</gl-link>
<gl-button>Submit</gl-button>

Do not use tabindex="0" on elements for screen readers to read

Screen readers can read text that is not tab accessible. The use of tabindex="0" is unnecessary and can cause problems, as screen reader users then expect to be able to interact with it.

<!-- bad -->
<p tabindex="0" :aria-label="message">{{ message }}</p>

<!-- good -->
<p>{{ message }}</p>

Do not use a positive tabindex

Always avoid using tabindex="1" or greater.

Icons

Icons can be split into three different types:

  • Icons that are decorative
  • Icons that convey meaning
  • Icons that are clickable

Icons that are decorative

Icons are decorative when there’s no loss of information to the user when they are removed from the UI.

As the majority of icons within GitLab are decorative, GlIcon automatically hides its rendered icons from screen readers. Therefore, you do not need to add aria-hidden="true" to GlIcon, as this is redundant.

<!-- unnecessary — gl-icon hides icons from screen readers by default -->
<gl-icon name="rocket" aria-hidden="true" />`

<!-- good -->
<gl-icon name="rocket" />`

Icons that convey information

Icons convey information if there is loss of information to the user when they are removed from the UI.

An example is a confidential icon that conveys the issue is confidential, and does not have the text “Confidential” next to it.

Icons that convey information must have an accessible name so that the information is conveyed to screen reader users too.

<!-- bad -->
<gl-icon name="eye-slash" />`

<!-- good -->
<gl-icon name="eye-slash" :aria-label="__('Confidential issue')" />`

Icons that are clickable

Icons that are clickable are semantically buttons, so they should be rendered as buttons, with an accessible name.

<!-- bad -->
<gl-icon name="close" :aria-label="__('Close')" @click="handleClick" />

<!-- good -->
<gl-button icon="close" category="tertiary" :aria-label="__('Close')" @click="handleClick" />

Tooltips

When adding tooltips, we must ensure that the element with the tooltip can receive focus so keyboard users can see the tooltip. If the element is a static one, such as an icon, we can enclose it in a button, which already is focusable, so we don’t have to add tabindex=0 to the icon.

The following code snippet is a good example of an icon with a tooltip.

  • It is automatically focusable, as it is a button.
  • It is given an accessible name with aria-label, as it is a button with no text.
  • We can use the gl-hover-bg-transparent! class if we don’t want the button’s background to become gray on hover.
  • We can use the gl-p-0! class to remove the button padding, if needed.
<gl-button
  v-gl-tooltip
  class="gl-hover-bg-transparent! gl-p-0!"
  icon="warning"
  category="tertiary"
  :title="tooltipText"
  :aria-label="__('Warning')"
/>

Hiding elements

Use the following table to hide elements from users, when appropriate.

Hide from sighted usersHide from screen readersHide from both sighted and screen reader users
.gl-sr-onlyaria-hidden="true" display: none, visibility: hidden, or hidden attribute

Hide decorative images from screen readers

To reduce noise for screen reader users, hide decorative images using alt="". If the image is not an img element, such as an inline SVG, you can hide it by adding both role="img" and alt="".

gl-icon components automatically hide their icons from screen readers so aria-hidden="true" is unnecessary when using gl-icon.

<!-- good - decorative images hidden from screen readers -->

<img src="decorative.jpg" alt="">

<svg role="img" alt="" />

<gl-icon name="epic" />

When to use ARIA

No ARIA is required when using semantic HTML, because it already incorporates accessibility.

However, there are some UI patterns that do not have semantic HTML equivalents. General examples of these are dialogs (modals) and tabs. GitLab-specific examples are assignee and label dropdowns. Building such widgets require ARIA to make them understandable to screen readers. Proper research and testing should be done to ensure compliance with WCAG.

Automated accessibility testing with axe

We use axe-core gems to run automated accessibility tests in feature tests.

We aim to conform to level AA of the World Wide Web Consortium (W3C) Web Content Accessibility Guidelines 2.1.

When to add accessibility tests

When adding a new view to the application, make sure to include the accessibility check in your feature test. We aim to have full coverage for all the views.

One of the advantages of testing in feature tests is that we can check different states, not only single components in isolation.

You can find some examples on how to approach accessibility checks below.

Empty state

Some views have an empty state that result in a page structure that’s different from the default view. They may also offer some actions, for example to create a first issue or to enable a feature. In this case, add assertions for both an empty state and a default view.

Ensure compliance before user interactions

Often we test against a number of steps we expect our users to perform. In this case, make sure to include the check early on, before any of them has been simulated. This way we ensure there are no barriers to what we expect of users.

Ensure compliance after changed page structure

User interactions may result in significant changes in page structure. For example, a modal is shown, or a new section is rendered. In that case, add an assertion after any such change. We want to make sure that users are able to interact with all available components.

Separate file for extensive test suites

For some views, feature tests span multiple files. Take a look at our feature tests for a merge request. The number of user interactions that needs to be covered is too big to fit into one test file. As a result, multiple feature tests cover one view, with different user privileges, or data sets. If we were to include accessibility checks in all of them, there is a chance we would cover the same states of a view multiple times and significantly increase the run time. It would also make it harder to determine the coverage for accessibility, if assertions would be scattered across many files.

In that case, consider creating one test file dedicated to accessibility. Place it in the same directory and name it accessibility_spec.rb, for example spec/features/merge_request/accessibility_spec.rb.

Shared examples

Often feature tests include shared examples for a number of scenarios. If they differ only by provided data, but are based on the same user interaction, you can check for accessibility compliance outside the shared examples. This way we only run the check once and save resources.

How to add accessibility tests

Axe provides the custom matcher be_axe_clean, which can be used like the following:

# spec/features/settings_spec.rb
it 'passes axe automated accessibility testing', :js do
  visit_settings_page

  wait_for_requests # ensures page is fully loaded

  expect(page).to be_axe_clean.according_to :wcag21aa
end

Make sure to specify the accessibility standard as :wcag21aa.

If needed, you can scope testing to a specific area of the page by using within.

Axe also provides specific clauses, for example:

expect(page).to be_axe_clean.within '[data-testid="element"]'

# run only WCAG 2.0 Level AA rules
expect(page).to be_axe_clean.according_to :wcag21aa

# specifies which rule to skip
expect(page).to be_axe_clean.skipping :'link-in-text-block'

# clauses can be chained
expect(page).to be_axe_clean.within('[data-testid="element"]')
                            .according_to(:wcag21aa)

Axe does not test hidden regions, such as inactive menus or modal windows. To test hidden regions for accessibility, write tests that activate or render the regions visible and run the matcher again.

You can run accessibility tests locally in the same way as you run any feature tests.

Known accessibility violations

This section documents violations where a recommendation differs with the design system:

  • link-in-text-block: For now, use the skipping clause to skip :'link-in-text-block' rule to fix the violation. After this is fixed as part of issue 1444 and underline is added to the GlLink component, this clause can be removed.

Resources

Viewing the browser accessibility tree

Browser extensions

We have two options for Web accessibility testing: