The a11y Monthly: Give your HTML elements an accessible name

At Yoast, I help improving Yoast's technology accessibility, spreading accessibility culture and blogging about it. I try to do my best to do the same for WordPress, where I'm contributing as a permanent core committer.

Recently, I joined a conversation where someone said a great part of accessibility is “subjective.” While I’d agree that sometimes the perception of accessibility is subjective, there are objective rules. I’m not referring just to the official specifications such as the Web Content Accessibility Guidelines or the ARIA Authoring Practices. There are practical rules every developer should know. One of the most important rules is about the accessible name. In this post, I’ll explain what an accessible name is and why it’s so important.[product_banner product=”technical-seo-training”]

How browsers interact with assistive technologies

Ever wondered where assistive technologies get the information they need? Screen readers, for example, don’t work as browsers do. Let me explain in non-technical terms. When browsers read a web page, they build a complete representation of all the objects in the page, where each object may have dozens or hundreds of properties. This is called the Document Object Model (DOM).

Screen readers don’t access the DOM directly. That would be a costly operation and could significantly impact performance. Instead, they use the Accessibility API which is built-in in every operating system and browser. Roughly speaking, the Accessibility API exposes to assistive technologies an accessibility tree which is a subset of the DOM tree. This is because assistive technologies don’t need the dozens or hundreds of properties exposed in the DOM. They just need a few properties for each object in a web page.

The most important pieces of information in the Accessibility API

In 1997, Microsoft released the Microsoft Active Accessibility (MSAA) which standardized for the first time four critical pieces of information for any user interface element:

Role: the type of object, such as a button

Name: a humanly understandable label for the object, such as the button text

State: the current condition of the control, such as “checked” for a checkbox

Value: the value of the object, such as the information in an editable text field (not all objects have a value)

Over time, operating systems have introduced different Accessibility APIs and they all provide the same four pieces of information, in different flavors.

While the default object role is inferred from the type of object, the name must be provided in our HTML. It’s a developer’s responsibility to code in a way to ensure every user interface control always has a meaningful name. If an accessible name isn’t provided in our HTML, then we’re breaking the rules established more than 20 years ago and we’re not allowing the Accessibility APIs to work as intended.

How the accessible name works

The accessible name of a user interface element is derived from different sources, also depending on the element’s type. Browsers use a sort of fallback mechanism to calculate the accessible name, called the Accessible Name and Description Computation. This fallback mechanism can get complex, and I don’t want to enter technical details. Let’s just make a simple example:

<a href="kittens.html">My super nice kittens</a>

In this example, the content of the link is the accessible name, and the element type is the accessible role. Assistive technologies would use this information exposed by the Accessibility API and, for example, screen readers would announce something like “link, My super nice kittens.”

In most cases, the accessible name is calculated from an element’s content, an attribute, or an associated element. There are several ways to provide a proper accessible name. What could go wrong when our HTML is poorly coded and doesn’t pass an accessible name to the Accessibility API?

What not to do

With a few examples I’ve collected from real cases, I’d like to give you an idea of what happens when there’s no accessible name.

Buttons without accessible name

I’ve seen this kind of HTML many times, even in recent projects. A button element, with an icon and styled in a way that looks like a nice user interface control:

<button class="menu-icon"></button>

Or a slightly different variant, with an SVG icon as the button content:

<button type="button" class="menu-icon">
<svg ... ></svg>
</button>

In both cases, there’s absolutely nothing that can be used as the accessible name. The buttons are empty; there’s no text at all. They could use an aria-label attribute or the SVG icon could use some enhanced accessibility. In the absence of an accessible name, screen readers would announce just the accessible role. Users will hear something like “button” and nothing else. They wouldn’t have any clue what the button purpose is. Fixing this would be very simple: just use some meaningful text for the button content. Alternatively, use some visually hidden text or an aria-label attribute.

Input fields without an accessible name

Email address:
<input type="text" name="email" value="" />

Input fields should always have a properly associated <label> element. In the example above, there’s just some text before the input field. There’s no way for the Accessibility API to establish a relationship between the text and the input field. Instead, a label element would establish such a relationship, giving the input field an accessible name. Alternatively, it is possible to use the aria-label or aria-labelledby attributes. In absence of an accessible name, screen readers would announce just the accessible role and say something like “edit text.” No clue about the type of data to enter in the field.

Linked images without an alt attribute

Images should use an alt attribute to describe what their function in a given context is. Purely decorative images must use an empty alt attribute. Meaningful images need a meaningful alt text to describe the image purpose. The W3C provides a very useful alt attribute decision tree which describes how to use it. Consider the example below:

The only content in the link is an image without any alt attribute. There’s nothing that can be used as an accessible name. Since it’s a link, screen readers will try to read something anyway, and they will try to use the only available thing: the image filename, in the hope it’s a meaningful filename. Unfortunately, in most of the cases, the filename is completely unrelated to the link’s purpose. In this case, screen readers will announce the link and image roles, and read out the whole file name, something like: “link, image, 145x142_1492700029699.TgrWeb_Q.jpg”

You can easily imagine the devastating impact on the usability of a website for screen reader users, especially if all the images in the page work this way.

Linked images without an empty alt attribute

A variant of the previous example is a linked image with an empty alt attribute. A very typical example of a website logo linked to the home page:

<a href="/">
<img src="logo.png" alt="">
</a>

At first sight, this example might look better. It is not. An empty alt attribute is a standardized way to instruct screen readers the image is decorative and can be safely ignored. However, since this is a link, screen readers will try to announce something anyway. The only available fallback is the link href attribute whose value is a slash. Not surprisingly, some screen readers will announce just “link, slash”:

Note: Only some screen readers are smart enough to figure out the website URL and announce that instead of “slash.”

Learn HTML deeply

Today, we live in an era where many advanced web technologies are available. They empower us to build awesome applications with very high-quality code standards. However, whatever the technology in use is, HTML is still the final layer of our communication. It’s what users see and use. When our HTML is poorly coded, our communication fails, and all the wonderful code we’ve written before doesn’t matter.

Rich, semantic HTML is what we need to improve our communication and help machines understand what we mean.

Want to help?

At Yoast, accessibility matters a great deal. We know it’s a process and we’re continuously improving, testing, iterating, and developing. We’re always open to feedback and contributions. Please do not hesitate to let us hear your voice. Please report any issues or potential improvements you notice in our products.