info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
---
# Accessibility & Readability
# 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](https://www.w3.org/TR/wai-aria-practices/#no_aria_better_bad_aria),
review the following recommendations before using `aria-*`, `role`, and `tabindex`.
Use semantic HTML, which typically has accessibility semantics baked in, but always be sure to test with
[relevant combinations of screen readers and browsers](https://www.accessibility-developer-guide.com/knowledge/screen-readers/relevant-combinations/).
In [WebAIM's accessibility analysis of the top million home pages](https://webaim.org/projects/million/#aria),
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.
## Provide accessible names to screen readers
To provide markup with accessible names, ensure every:
-`input` has an associated `label`.
-`button` and `a` have child text, or `aria-label` when text isn’t present.
For example, an icon button with no visible text.
-`img` 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.
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.
Ensure the accessible name is descriptive enough to be understood in isolation.
```html
// bad
<button>Submit</button>
<ahref="url">page</a>
// good
<button>Submit review</button>
<ahref="url">GitLab's accessibility page</a>
```
## 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.
Use semantic HTML, such as `a` and `button`, which provides these behaviours by default.
See the [Pajamas Keyboard-only page](https://design.gitlab.com/accessibility-audits/2-keyboard-only/) for more detail.
## Tabindex
Prefer **no**`tabindex` to using `tabindex`, since:
- Using semantic HTML such as `button` implicitly provides `tabindex="0"`
- Tabbing order should match the visual reading order and positive `tabindex`s interfere with this
### Avoid using `tabindex="0"` to make an element interactive
Use interactive elements instead of `div`s and `span`s.
For example:
- If the element should be clickable, use a `button`
- 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.
We have two options for Web accessibility testing:
-[axe](https://www.deque.com/axe/) for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/)
-[axe](https://www.deque.com/axe/) for [Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd)
The [axe](https://www.deque.com/axe/) browser extension (available for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/) and [Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd)) provides running audits and feedback on markup, CSS, and even potentially problematic color usages.
### Other links
Accessibility best-practices and more in-depth information are available on
-[The A11Y Project](https://www.a11yproject.com/) is a good resource for accessibility
[the Audit Rules page](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules) for the Chrome Accessibility Developer Tools. The [Awesome Accessibility](https://github.com/brunopulis/awesome-a11y) list is a compilation of accessibility-related material.
@@ -6,6 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
...
@@ -6,6 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# HTML style guide
# HTML style guide
See also our [accessibility page](../accessibility.md).
## Semantic elements
## Semantic elements
[Semantic elements](https://developer.mozilla.org/en-US/docs/Glossary/Semantics) are HTML tags that
[Semantic elements](https://developer.mozilla.org/en-US/docs/Glossary/Semantics) are HTML tags that
...
@@ -52,30 +54,27 @@ Button tags requires a `type` attribute according to the [W3C HTML specification
...
@@ -52,30 +54,27 @@ Button tags requires a `type` attribute according to the [W3C HTML specification
<buttontype="button"></button>
<buttontype="button"></button>
```
```
### Button role
If an HTML element has an `onClick` handler but is not a button, it should have `role="button"`. This is [more accessible](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role).
```html
// bad
<divonClick="doSomething"></div>
// good
<divrole="button"onClick="doSomething"></div>
```
## Links
## Links
### Blank target
### Blank target
Avoid forcing links to open in a new window as this reduces the control the user has over the link.
However, it might be a good idea to use a blank target when replacing the current page with
the link makes the user lose content or progress.
Use `rel="noopener noreferrer"` whenever your links open in a new window, i.e. `target="_blank"`. This prevents a security vulnerability [documented by JitBit](https://www.jitbit.com/alexblog/256-targetblank---the-most-underestimated-vulnerability-ever/).
Use `rel="noopener noreferrer"` whenever your links open in a new window, i.e. `target="_blank"`. This prevents a security vulnerability [documented by JitBit](https://www.jitbit.com/alexblog/256-targetblank---the-most-underestimated-vulnerability-ever/).
When using `gl-link`, using `target="_blank"` is sufficient as it automatically adds `rel="noopener noreferrer"` to the link.
