What's in an (accessible) name?

Everything in an (accessible) UI needs an (accessible) name. For most controls, that’s automatic—they’ll have a good one by default. But sometimes you’ll need to specify one manually.

A forlorn robot wearing a dinosaur T-shirt stands on a balcony pondering a rose A forlorn robot wearing a dinosaur T-shirt stands on a balcony pondering a rose

Let’s walk through how to use accessible names (and accessible descriptions!) in your UI. For example, you’ll know to name this button Visit DinoPark—and to put other content into the description instead:

🤔 What should the name be?

What is an “accessible name” and “accessible description”?

Briefly: beyond their internal visual tree of controls & their children, most UI frameworks expose a programmatic one called the accessibility tree. ATs (like screen readers) can read this accessibility tree using standardized APIs (like UIA on Windows, NSAccessibility on macOS & iOS, ATK/​AT-SPI on Android & Linux, and ARIA—which browsers translate into the other APIs — on the web).

As devs building accessible UI, we decide:

  1. Which controls appear in the accessibility tree,
  2. What properties are set on each control, and
  3. When to send notifications about changes to these controls & properties.

The most important of these properties is the control’s name (often called its accessible name to distinguish from its visible label).

The accessible name is usually the first thing a screen reader announces about a control, whereas other properties (like accessible description; we’ll get to it) announce later. For example:

Visit DinoPark, button, start your DinoPark visit today

It’s the first thing screen reader users hear, so a good accessible name is important.

Accessible names are usually correct — by default

But by default, most controls already have good accessible names.

UI frameworks vary, but usually they’ll automatically name controls based on visible content: a button with the label “Edit” will be named Edit, a textbox labelled “First name” will be named First name, etc. WinUI controls automatically generate names for themselves in most cases, as do SwiftUI controls, as does web content.

It’s truly rare to need a custom name. For example, these are all correct:

✅ These are all good

When do I need a custom accessible name?

In fact, I usually only use explicit names in a few circumstances:

And, in rare cases:

What makes a name unclear? Let’s explain.

What is required?

First, let’s discuss what’s required of accessible names.

You probably rely on WCAG for your accessibility requirements (they’re a big part of what my work uses), but they’re surprisingly terse about names. Here’s what they require:

Instead, most WCAG recommendations about accessible names come from separate, non-normative guidance, Providing Accessible Names and Descriptions (worth reading). They offer 5 “cardinal rules” and several guidelines, but nothing mandatory. This is a signal: good accessible names can’t be chosen merely by following requirements or an algorithm—they come from deliberate design.

For example, although both of these buttons are accessibly compliant, they are both poorly designed — even if the issue is only obvious to screen reader users:

🤔 This is a design problem

Designing good accessible names

The guidelines at Providing Accessible Names and Descriptions are a great start, but I would summarize them like this — an accessible name should:

And, the one actual rule about content (WCAG 2.5.3), it must:

These guidelines become clear when you begin by understanding who you’re designing for: accessible names are used mostly by ① screen reader users and ② voice control users. For example:

This explains other guidance like “put the most distinguishing and important words first” and “do not include the word ‘button’ in the name of a button”. It all stems from the purpose of an accessible name—clearly identifying controls to people who cannot see or use the whole screen at once. The rest follows.

Alternative: just use the accessible description

Choosing good accessible names becomes simpler if you understand the alternatives to setting long ones.

Simply put: just use other properties—like the accessible description.

I often work with customers who want to ensure screen readers announce something: error messages, essential instructions, status, whatever. While you should be wary of trying to force specific announcements (see (Don’t) make Narrator read things), using other properties is a great way to expose information to screen readers. It’s method 2 in that article!

Unlike the accessible name, properties like accessible description have very few strict requirements—they must be correct & descriptive if present, but their use is only “strongly encouraged”, never required (WCAG 1.3.1). No, they’re designed to be flexible. In fact, although ARIA only has 1 descriptive property—accessible description—UIA on Windows has several properties you can use, from descriptions to help text to status. And macOS & iOS support literally any key-value pairs. No matter what you use, though, separating your names from your descriptions gives ATs flexibility — descriptions will still be read by default, but your users can change their order, read them separately, or even skip them altogether in familiar UI.

This flexibility makes choosing names much easier: put visible labels in the accessible name—put everything else in the description.

Examples

Let’s work through some examples.

Example: accessible names for images, emoji, and icons

Let’s start by fixing our initial example.

The emoji icon is clearly illustrative, so the emoji’s title ("sauropod") is probably not a great name. The button has a text description below to help visual users (your buttons do have a text label or a tooltip, right?), but it’s a bit wordy. Since the button already has a succinct tooltip (from its title), let’s use that as the name, and the wordier text as the description:

✅ A well-chosen name for our initial example

As a counterpoint, here we remove redundant emojis from the accessible name (since the rest of the label sufficiently describes the control):

✅ Hidden emojis, icons, and images

Example: use accessible description instead

Let’s fix the “Pay now” example from earlier.

It was worth distinguishing visually, so distinguish it for AT users, too. Use an accessible description instead of making the accessible name absurdly long:

✅ Use description instead

Example: go beyond the visible label

Here’s a rare example where the visible label isn’t clear enough to distinguish the controls.

In fact, the design relies on layout cues that would be very hard to understand in a screen reader. You could add extra text to the accessible description, like above, but since this text is vital to disambiguate the buttons, it makes sense to modify the name. Besides, the small note about the T-Rex tour is a better use of the accessible description.

Notably, I made a design decision to put the verb last in the accessible name ("Stegosaurus tour register"). Since all the buttons have the same verb, I use the tour name first — to lead with the most-selective words first so scanning is easier. It’s probably not necessary here (and also a bit controversial: WCAG 2.5.3 recommends putting visible label text at the start of the name), but worth a demonstration:

✅ Handling unclear labels

Example: create contexts

Here’s another example that emphasizes the design aspect of choosing names.

The controls in the DinoPark control panel below all have similar visible labels, but different effects. For example, we have ① a button to “Open” the escape tunnel to the helipad and ② a similar one to “Open” the tunnel to the raptor enclosure. The visible labels alone are ambiguous to screen reader users — when tabbing between them, they’ll simply hear Open, button. Dangerous.

The WCAG naming guidelines above recommend choosing unique names for each: Open helipad tunnel & Open raptor cages tunnel.

But I, however, prefer contexts—if you name their containers “Tunnel to helipad” & “Tunnel to raptor cages”, you create contexts that screen readers will announce automatically when entered. This makes the screen reader experience a lot clearer in more-complicated interfaces: for example, the tunnel to the hotel can be opened and sealed permanently, and unique names would make things much wordier (Seal permanently, tunnel to hotel?).

This approach is often simpler, but it’s a trade-off: what will happen when a voice control user says "Click Open"?

✅ Create contexts

Example: bad names

And finally, let’s show some common mistakes:

❌ Bad names

Hopefully it makes sense why these are mistakes: they hide critical information, add too much text, or otherwise make the UI more annoying to use.

Conclusion

In short, for accessible names:

And if you can’t, keep those names:

And make sure they contain any visible label. Put everything else somewhere else — like the accessible description.

The first words in the ARIA guidance (Read Me First) are “No ARIA is better than Bad ARIA”. We want to make UI that’s accessible to everyone. But often that means doing nothing at all: your framework usually chooses good names automatically. Default accessible names can be confusing or difficult to use. But incorrect, custom accessible names can be impossible to use.

I hope now it’s clear why.

Thanks to Atherai Maran for editing & the dinosaur drawing. Thanks to Doug Geoffray for consulting. Tested with Narrator & NVDA in Edge on Windows 11.

Further reading

WCAG rules & guidance:

Related articles:

Appendix: About the article title

I remember reading an article with this title eons ago, but I haven’t been able to find it since. So I decided to write my own 😅. Can you find it? I’d love to link it.