accessibility.md

stage: none
group: unassigned
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments

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

• Text, select, checkbox, radio, file, and toggle inputs have accessible names.
• Buttons, links, and images have descriptive accessible names.
• Icons
  • Non-decorative icons have an aria-label.
  • Clickable icons are buttons, that is, <gl-button icon="close" /> is used and not <gl-icon />.
  • Icon-only buttons have an aria-label.
• Interactive elements can be accessed with the Tab key and have a visible focus state.
• Elements with tooltips are focusable using the Tab key.
• Are any role, tabindex or aria-* attributes unnecessary?
• Can any div or span elements be replaced with a more semantic HTML element like p, button, or time?

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 with descriptive accessible names

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 styled like buttons

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.

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