Accessible Custom Fields

As part of our journey toward achieving WCAG 2.1 AA compliance, we’ve been working to ensure that custom fields are accessible to all users.

While running manual accessibility tests, we found that some information — while visually associated with fields — wasn’t being conveyed to screen reader users. This information included modification status, instructions, and error messages.

We recently released some updates to streamline how these are conveyed to assistive technology users.

aria-describedby and you

The aria-describedby attribute provides a way of identifying elements that provide extra detail about the element in question.

To use it, we pass a list of IDs in the aria-describedby attribute of our field elements. This exposes additional information about the field to the browser’s accessibility API. Now, an assistive technology can query the accessibility API to get all those extra pieces of information.

When a screen reader user focuses on a custom field’s input, they won’t just hear the field name and whether or not it’s required. They’ll also be able to access:

• Modification status
• Instruction text
• Error messages

The following screenshot shows the computed accessibility properties of a text field that’s been modified.

Creating accessible fields

First, what does the WCAG documentation have to say about accessible form fields? Both Success Criterion 3.3.2: Labels or Instructions and Success Criterion 2.4.6 Headings and Labels cover field labels and instruction text.

Feel free to dig into the guidelines at your leisure. But for the purposes of this article, let’s focus on the intent of these success criteria.

Labels and instructions should:

• Make the purpose of the field clear to all users
• Help users enter form information correctly
• Keep users from entering incomplete or incorrect information

So providing adequate instructions for content authors isn’t only an accessibility requirement.

It’s essential for creating a great author experience.

Here are a few rules of thumb to keep in mind when building out your custom fields.

Note any constraints

In Craft, it’s possible to set constraints or limitations on different field types. For example, you can:

• Require that a Matrix field has a minimum and/or maximum number of blocks
• Limit a number field to only accept values inside of a specified range

To make your fields fully accessible, you need to share those constraints with authors. And ideally before the field fails validation.

Let’s look at a few examples of labels and instruction text in varying degrees of helpfulness.

Example 1: Worst

Here, I’ve added a new field to my Blog articles. It’s called “Cards to Show”.

There are a couple issues here:

1. The label is vague. What are these “cards” it’s referring to?
2. Did you know this is actually a number field? I didn’t until I started typing in letters and nothing happened.

Example 2: Better

The following label is more helpful, if a bit verbose. Now I know it’s referring to the “Related Article” cards that will show on the front-end template. And that it will take a number.

However, when we try to save the new value, we’re hit with an error:

Example 2: Best

And here's the winner.

We’ve done everything in our power to make things simple for our content authors. Now they’ll know exactly what type of values the field will take, and any constraints on the data.

Don’t rely on placeholder text

Some fields give you the option to add placeholder text when the field isn’t filled out yet.

Placeholder text isn’t fully supported by all forms of assistive technology, so it’s best to assume all placeholder text is purely decorative.

There are a couple quirks to keep in mind here:

1. Some screen readers don’t support placeholder text, and it simply isn’t conveyed to users.
2. A screen reader might read placeholder text in addition to everything else. If you include field instructions, having verbose placeholder text also being read could get annoying. Quick.

Another issue with placeholder text is that it’s only visible when the field is empty. Many users, including users with cognitive disabilities, may find it difficult to retain that information once they start entering text in the field.

So if you choose to include placeholder text, keep it short and sweet. And strictly use it to enhance your field instructions, not take their place entirely.

Improve your label text

There may be some areas in the control panel where you’re unable to add field-specific instruction text.

One example is any input field inside of a table. The table field instructions will be read out for each of these fields.

But any field-specific instruction or hints should be included in the field name.

For example, I’ve added a table field for displaying product recommendations on my blog, with columns for prices and ratings. Here are a couple ways I improved the labeling:

1. I want authors to use a specific format for the price string ($XX.XX), so I’ve included that as part of the label name.
2. The ratings column takes a number, so I’ve clarified the label by suggesting a range of numeric values.

Key Takeaways

The WCAG guidelines on labels and instructions are a great example of how accessibility improvements can benefit everyone.

Taking the time to improve the clarity of your labels and instructions can have a great impact on the AX of your Craft site.

To learn more about form accessibility, check out the following resources:

• Understanding Success Criterion 2.4.6: Headings and Labels
• Understanding Success Criterion 3.2.2: Labels and Instructions
• Web Accessibility Tutorials: Form Instructions
• Don’t Use the Placeholder Attribute