Labels and Hints in DLS v7

The DLS (Design Language System) is in the midst of building our next major version, v7, of our React components, and we wanted to give a deeper look into how we’re tackling accessibility with regards to labels and hint text.

As a side note, DLS v7 is a work in progress, so what you see here might change.

Labeling and Accessibility

For many components, a label is required. This label should be programmatically associated with the component to ensure that screen reader users receive the same contextual information available to sighted users.

With this in mind, we wanted to offload the burden of handling accessible labels off the consumers as much as possible while still providing flexibility for custom labels.

Providing Labels

Native HTML and ARIA offer many avenues to provide labels. How to properly label depends on the element itself. Some elements have native HTML, so we strive to use semantic, native HTML where possible. My go-to resource is the Mozilla MDN docs to get element specific information.

Native HTML

Using native HTML is preferred because it’s more universally supported and understood by assistive technologies (e.g. screen readers). For example, for <button> elements, its inner text is its accessible name, which effectively functions as its accessible label.

1<button type="button">Add to favorites</button>;

This button will read “Add to favorites” to screen reader users, which is our desired behavior.

Another common example is <input> elements. The native HTML approach is to use a <label> with a for attribute (htmlFor in React) that has the id of the input its labeling.

1<label for="peas">Do you like peas?</label>
2<input type="checkbox" name="peas" id="peas" />

Code snippet pulled from MDN input.

ARIA

When native HTML isn’t feasible, use ARIA, specifically the aria-labelledby or aria-label. While these are powerful, they should be used judiciously, since over reliance or incorrect use of ARIA can harm accessibility rather than enhance it.

We’ll do a high level overview, but please refer to the links above for a deeper explanation of each attribute.

aria-labelledby

aria-labelledby allows us to pass the id(s) of other elements on the page to define an accessible name. An important use case is that it can take multiple ids, so you can associate multiple labels to an element. This will become important later in this blog, since we use this in DLS v7.

Another important thing to note from the MDN docs, is that ”aria-labelledby takes precedence over all other methods of providing an accessible name, including aria-label, <label>, and the element’s inner text”.

For the snippet below, the screen reader will read “Do you like carrots?” because its aria-labelledby is overriding the label that’s provided with the for attribute.

1<label id="carrot-label">Do you like carrots?</label>
2<label for="vegetable-checkbox">Do you like peas?</label>
3
4<input type="checkbox" name="vegetable" id="vegetable-checkbox" aria-labelledby="carrot-label" />

For the snippet below, the screen reader will read “Do you like carrots?” because the aria-label is being overridden.

1<label id="carrot-label">Do you like carrots?</label>
2
3<input type="checkbox" name="vegetable" id="vegetable-checkbox" aria-labelledby="carrot-label" aria-label="Do you like peas?"/>

aria-label

If there is nothing visible in the DOM to use with aria-labelledby, then aria-label can be used to define a string value, which labels the element. Since this content is not visible, be sure to use this cautiously because it introduces invisible content that can be missed by sighted users.

This pattern is commonly used to label icon buttons without visible text, such as a close button.

We don’t use this pattern as much within our DLS React components, but it’s still available for consumers to pass through via props. We prefer aria-labelledby over aria-label because it offers more flexibility, especially with multiple labels.

1<button aria-label="Close">
2  // insert close icon
3</button>

Labeling Considerations During the Dev Build

During the build, our engineers had a few considerations in mind:

1. Provide an easy way for consumers to import components that match the designs in Figma
2. Be flexible in our component API to allow customization
3. Offload the responsibility of accessibility to the DLS (as much as possible)

Let’s dive into what these mean for our component code.

Matching our Figma Designs

In Figma and in our docs, you’ll see an input component used with a label. With v6, consumers had to import the <Input> and <Label> React components separately and configure the HTML attributes themselves in order to match the designs. This presents opportunity for confusion and accessibility errors.

Here’s a simplified v6 React code sample:

1import { Label, Input } from '@americanexpress/dls-react';
2
3export const Form = () => (
4  <>
5    <Label htmlFor="name-input">
6      Please enter your name
7    </Label>
8    <Input id="name-input" />
9  </>
10);

Assuming that this is the common use case, we saw an opportunity to streamline this. If an <Input> should always be used with a label (most likely the DLS <Label>), then why don’t we ship the label within the component itself? Thus, the consumer doesn’t need to import the <Label> every time they want to use <Input>, and the DLS team can handle the HTML and ARIA attributes to guarantee it’ll be accessible.

Here’s a simplified v7 code sample:

1// consumer application
2import { Input } from '@americanexpress/dls-react-seven';
3
4export const Form = () => (
5  <Input id="name-input" label="Please enter your name" />
6);

For the consumers, if they want to use the built-in label (that matches the Figma designs), they just provide an id to the <Input> and a string to the label prop, and the component will handle the rest.

Within the React component:

1// v7 Input.jsx
2import { Label } from '../Label.jsx';
3
4export const Input = ({ label, id }) => (
5  <>
6    { label && <Label htmlFor={id}>{label}</Label> }
7    <input id={id} />
8  </>
9);

The built-in <Label> will match our Figma designs. We set the htmlFor id value correctly to associate the <Label> with the <Input> to abstract this away from the consumers.

Allowing Customization

As a design system, we strive to provide guidelines while being flexible to the varying needs of our users. With that in mind, we’ve built in ways for users to customize their labels if the built-in label doesn’t fit their requirements.

The label prop can be omitted to exclude our DLS built in label. In this scenario, the responsibility of providing accessible labels falls onto the consumer. Consumers can accomplish this with the aria-labelledby and aria-label attributes. For <input>s, the for HTML attribute with a native <label> is preferred.

Let’s say a consumer wanted to have different label styling.

1import { Label, Input } from '@americanexpress/dls-react-seven';
2
3export const Form = () => (
4  <>
5    <Label className="pad-2 dls-deep-blue" htmlFor="name-input">
6      Please enter your name
7    </Label>
8    <Input id="name-input" />
9  </>
10);

If you aren’t using the <label> element, have different label placement in your designs, or have multiple labels, aria-labelledby can be used.

Recall that aria-labelledby can take multiple ids to apply multiple labels to an element.

1import { Input } from '@americanexpress/dls-react-seven';
2
3export const Page = () => (
4  <>
5    <p id="first-label">
6      First Label
7    </p>
8    <p id="second-label">
9      Second Label
10    </p>
11    <Input aria-labelledby="first-label second-label" />
12  </>
13);

This example below has hint text (within the <p> tag) that sits between the heading and the input that the heading is labeling. This doesn’t match our design, and there’s no way to insert the paragraph hint text via props or React children. Also, our built-in label isn’t using an <h3> under the hood. This is a prime example where customization is needed. Luckily our component can handle this use case with aria-labelledby.

1import { Input } from '@americanexpress/dls-react-seven';
2
3export const Page = () => (
4  <>
5    <h3 id="name-heading">Name</h3>
6    <p id="name-hint">Please capitalize your name</p>
7    <Input aria-labelledby="name-heading" aria-describedby="name-hint" />
8  </>
9);

You may have noticed the aria-describedby in the above example, which provides a good segue into our built-in hint text.

Hint Text

Often times, components benefit from including hint text to provide additional information to the user. We often see this in form inputs. Since our Figma designs include a hint text with inputs, we followed the same thought process as labels and decided to ship our components with the hint text built in.

Now, we’ll shift our focus away from aria-labelledby and aria-label and focus on aria-describedby and how it’s used for hint text and descriptions. I’ll be using “hint text” and “description” interchangeably in this section.

What’s the difference between labels and hint text?

A common accessibility question is when to use aria-describedby and aria-labelledby. It’s a fair question; they are indeed very similar.

To answer this, it’s helpful to reframe it by asking yourself what is essential to describing the purpose of the component (labels) versus what is providing additional information that might be needed (descriptions). A good rule of thumb is that the label should be concise, while the description can be more verbose. The MDN aria-describedby page provides more detail.

aria-describedby

Unlike aria-labelledby and labels, the hint text associated via aria-describedby doesn’t need to be visible. Thus, it’s possible to have hint text that’s available only to screen reader users. This is okay because sometimes sighted users can gather contextual information from the visuals of the component.

For example, in our v6 <DatePicker>, the date is shown like 8/17/2023, thus sighted users can infer that the forward slash / is needed when manually entering the date. It would be redundant to provide the same information visually, but it would be immensely helpful to provide that information to non-sighted users with hidden hint text.

Like aria-labelledby, aria-describedby can also take on multiple ids to associate multiple descriptions to an element.

Hint Text in DLS v7

Our component API reflects the points discussed above, and we follow the same considerations from labeling in our dev build. The the same as labels, with the exception that consumers can visually hide hint text with our isHintVisible prop.

Matching our Figma Designs

We’ve streamlined our <Input> to ship the hint text within the component itself. For the consumers, if they want to use the built-in label (that matches the Figma designs), they just provide an id to the <Input> and a string to the hint prop, and the component will handle the rest.

An example of the default use case, which is a consumer who wants visible hint text.

1import { Input } from '@americanexpress/dls-react-seven';
2
3export const Page = () => (
4  <Input label="Name" hint="Please capitalize your name" />
5);

Visually hidden hint text that is still read to the screen reader:

1import { Input } from '@americanexpress/dls-react-seven';
2
3export const Page = () => (
4  <Input
5    label="Name"
6    hint="Please capitalize your name"
7    isHintVisible={false}
8  />
9);

Allowing Customization

If a consumer doesn’t want visible or screen reader hint text, then they can omit the hint prop. Unlike labeling, hint text isn’t required, so there’s nothing else required of the consumer to be accessible. They can use aria-describedby if they have different styling or multiple hints.

Different styling:

1// consumer application
2import { Hint, Input } from '@americanexpress/dls-react-seven';
3
4export const Form = () => (
5  <>
6    <Hint className="pad-2 dls-deep-blue" id="name-hint">
7      Please capitalize your name
8    </Hint>
9    <Input
10      id="name-input"
11      label="Please enter your name"
12      aria-describedby="name-hint"
13    />
14  </>
15);

Multiple Hints:

1import { Hint, Input } from '@americanexpress/dls-react-seven';
2
3export const Form = () => (
4  <>
5    <Hint id="first-hint">
6      First Hint
7    </Hint>
8    <Hint id="second-hint">
9      Second Hint
10    </Hint>
11    <Input
12      id="name-input"
13      label="Please enter your name"
14      aria-describedby="first-hint second-hint"
15    />
16  </>
17);

Feedback

We want to hear from you! Are you excited about accessibility or have questions about the impact on your team’s work? Let us know on slack in #dls-tech or #dls-design or by emailing dls@aexp.com.

References

• Mozilla MDN docs
• MDN input
• aria-labelledby
• aria-label
• aria-describedby