Skip to content

Accessibility

General Practices

As a general rule, accessible software is achieved by following web development best practices. As Treeherder uses the react-bootstrap library, it is recommended to use one of its components, if possible.

If you can not find a suitable component, prefer HTML5 semantic tags and avoid using generic tags, such as span and div. Moreover, try to use more headings (h1 to h6) whenever possible, because screen readers users usually navigate by headings and that is only possible when developers insert them in the code.

If you can build your layout neither with react-bootstrap nor with semantic tags, please insert aria-role in them. There are examples of how to use aria-role in: Tables, Progress Bar, List.

aria-role is important because it gives meaning to the generic HTML tag. That gives some direction to screen readers on which functionalities to provide and some information to users.

In summary, implement your layout trying to use these in the following order:

  1. Use react-bootstrap;
  2. Use HTML semantic tags;
  3. Use aria-role attributes.

Font Awesome

Treeherder also uses the Font Awesome library for some icons. Usually, there is no need to insert an additional explanation to them. However, if the icon has a semantic meaning, you can insert it by adding a title prop in the FontAwesomeIcon component.

<FontAwesomeIcon icon={icon} title="Icon description" />

Colors

Treeherder uses Bootstrap color utility classes. A few colors were modified in order to meet WCAG standards for color contrast.

Please use this custom color according to the following table:

Bootstrap Color Treeherder Color
btn-info btn-darker-info
text-info text-darker-info
btn-secondary btn-darker-secondary
text-secondary text-darker-secondary

For example, if inserting a text color into an element, use className="text-darker-info", instead of using className="text-info".

In some react-bootstrap components, you can insert a prop specifying its color. In that case, you use only the color name, without its prefix.

Component prop color
darker-info
darker-secondary

For example:

<Button variant="darker-info">
  Info colored button with contrast passing score
</Button>

Known react-bootstrap components that accept the variant prop and work with custom Treeherder colors: Badge, Button, Card, Dropdown, Navbar, ProgressBar, Spinner.

In case you need to add more custom colors, please add on treeherder-custom-styles.css style sheet.

Inserting new colors

If you add new colors to the style sheets, please make sure the text and background color combination passes the minimum contrast ratio defined by WCAG.

In order to check if it passes, you can use WebAIM contrast checker or use Firefox's Accessibility Devtools.

Red and Green

Red and green colors are not very noticeable for some types of color deficiency. For that reason, it is recommended to insert an accompanying icon, such as a checkmark (for success) or an exclamation point (for warning or error).

For that task, FontAwesome is a supported choice.

Images

Image HTML tag

If you add an image, make sure you also write an alternative text for it. The text should be descriptive and support the screen reader user.

<img src={image} alt="A description of the image">

If you are not sure how to write this, please refer to this guide.

SVG

For SVG images, do the following:

  • <svg> should have aria-labelledby attribute, with the ids of the following elements, separated by a blank space. It should also have a role="img";
  • As the first child of <svg>, add <title> with an id attribute. The content of this element should be the title of the image;
  • (Optional) Following <title>, you can add <desc>, which describes the image. You should also add an id.
<svg aria-labelledby="imageTitle imageDesc" role="img">
  <title id="imageTitle"> A title of this image </title>
  <desc id="imageDesc"> A description of this image </desc>
  // ...
</svg>

If your case is more specific, please check this guide.

Interactive elements

When creating elements that have event listeners, prefer any component of the react-bootstrap interactive elements. Examples are: Button, Form.Control, Dropdown. You can also choose a HTML <a> element.

If you need to insert an event listener in a non-interactive element, such as a span, add also an aria-role of button, link, checkbox, or whatever seems closer to the functionality of the element.

<span onClick={someFunction} aria-role="button">
  Unconventional button
</span>

There is a special case when you are creating a dropdown menu. First of all, try to follow react-bootstrap's Dropdown structure.

Lastly, insert an additional as prop to Dropdown.Item component if needed.

<Dropdown.Item as="a"> Menu Item </Dropdown.Item>

Forms, inputs and buttons

Apart from inserting high color contrast combinations in buttons, also make sure it has a :focus style (usually a blue outline is enough). If you use react-bootstrap's Button component, this is added by default, hence it is recommended.

In case the content of the button is not a text (an icon or graphical element, for example), this element should have an aria-label, explaining what it does.

<Button aria-label="Bookmark alert 12345" onClick={onClickFunction}>
  <FontAwesomeIcon icon={icon} />
</Button>

For input and checkbox, those are important to be labeled - placeholders are not enough for screen reader users. For example, when inserting an email input and a checkbox, using react-bootstrap, the structure should be:

<Form>
  <Form.Group>
    <Form.Label htmlFor="email">Email</Form.Label>
    <Form.Control
      type="email"
      name="email"
      id="email"
      placeholder="Insert your email"
    />
  </Form.Group>

  <Form.Group>
    <Form.Check type="checkbox" label="I agree with the terms" />
  </Form.Group>
</Form>

If in doubt, please check the react-bootstrap Form documentation.

Specific elements

Progress Bar

Across Perfherder, there are some Progress Bars, which are built using react-bootstrap components. It is recommended to add an aria-label to the wrapping component, explaining the values of the bar.

For example:

<ProgressBar
  aria-label={`Description of progress bar. Metric: ${finalValue}`}
>
  <ProgressBar now={valueOne} />
  <ProgressBar now={valueTwo} />
</ProgressBar>

Tables

In tables, there should always be headers.

<Table>
  <thead>
    <tr>
      <th> First header </th>
      <th> Second header </th>
      <th> Third header </th>
    </tr>
  </thead>
  <tbody></tbody>
</Table>

Also, if you are not using <table> tag or react-bootstrap's Table component to create the table, please use all the necessary role attributes.

Alternatively, you may choose to use the React Table library. The only requirement here is to insert a role="table", like this:

<ReactTable
  getTableProps={() => ({ role: 'table' })}
/>

Other Components (Third-Party)

Take special care when bringing in new elements/components to the app. They should have a good documentation on accessibility and should be tested beforehand by an a11y fellow.

References