
## Table of Contents

1. [Disclaimer](#disclaimer)
1. [The Announcement](#the-announcement)
1. [The Marketing and Documentation](#the-marketing-and-documentation)
1. [A Few Quick-ish Tests](#a-few-quick-ish-tests)
1. [Some Accessibility Issues](#some-accessibility-issues)
1. [In Summary](#in-summary)
1. [Related Resources](#related-resources)

## Disclaimer

I'm a neurodivergent and multiply disabled expert in web accessibility. I have a software engineering degree and almost a decade of software engineering experience. I am currently a self-employed consultant in software engineering and accessibility. ([Reach out if you want to collaborate](https://semanticfish.com)!)

This article is a few hours of free labor and close to half of what I'd charge for a 1-week sprint in a contract. This is to say I spent valuable time and limited energy doing work that should paid good money. I'm not saying it has to be _me_, but it should be _someone_ with expertise in accessibility.

## The Announcement

On July 5th, 2024, shadcn/ui Charts were announced on X.

<figure>
  <img aria-labelledby="announcement-caption" src="https://res.cloudinary.com/ashleemboyer/image/upload/article-images/announcement_tcyeih.png" />
  <figcaption aria-hidden id="announcement-caption">X post by shadcn on July 5, 2024, at 6:22 pm. Introducing Charts. A collection of chart components that you can copy and paste into your apps. Built on top of Recharts. Beautifully designed. Open Source.</figcaption>
</figure>

## The Marketing and Documentation

On the shadcn/ui home page, there's a new Charts navigation link and an "Introducing Charts" call-to-action in the main content area.

The first links to the [Charts Library page](https://ui.shadcn.com/charts). It contains a few dozen examples of area, bar, line, pie, radar, and radial charts. There is also a widget for changing the color scheme: default, palette, sapphire, ruby, emerald, daylight, and midnight. There are no mentions of the keywords accessibility, keyboard, or screen reader.

The second links to the main [`Chart` component documentation](https://ui.shadcn.com/docs/components/chart). It has an interactive demo and documents installation, grids, axes, tooltips, legends, theming, and other configurations.

At the very end of the page is an Accessibility section. Through one boolean prop ([a React term](https://react.dev/learn/passing-props-to-a-component)), it states the ability to add "keyboard access" and "screen reader support". It also provides a copy-paste-able short example code snippet.

<figure>
  <img aria-labelledby="accessibility-section-caption" src="https://res.cloudinary.com/ashleemboyer/image/upload/article-images/accessibility-section_jz430y.png" />
  <figcaption aria-hidden id="accessibility-section-caption"><code>Chart</code> documentation Accessibility section. You can turn on the <code>accessibilityLayer</code> to add an accessible layer to your chart. This prop adds keyboard access and screen reader support to your charts.</figcaption>
</figure>

## A Few Quick-ish Tests

### Test 1: "Your First Chart" Documentation Demo

Video description coming soon.

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/iBeMgw7NCgE?si=xtTVM-fI2AzCPqHb" title="YouTube embed: 'Your First Chart' test"  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />

### Test 2: "Add a Grid" Documentation Demo

Video description coming soon.

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/XqO5hG75zF0?si=lEhTy9zE4CwNzKQD" title="YouTube embed: 'Add a Grid' test"  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />

### Test 3: "Add an Axis" Documentation Demo

Video description coming soon.

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/jVoZYGOVSLw?si=zOX9ep2b1h_jJa07" title="YouTube embed: 'Add an Axis' test"  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />

### Test 4: "Add Tooltip" Documentation Demo

Video description coming soon.

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/oKF10Qb2ko0?si=YbS7JkUIIb15cwGo" title="YouTube embed: 'Add Tooltip' test"  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />

### Test 5: "Add Legend" Documentation Demo

Video description coming soon.

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/wAnMFmaZgmY?si=h4etkm3y5Meiw3PA" title="YouTube embed: 'Add Legend' test"  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />

### Test 6: With and Without VoiceOver's "Quick Nav" mode

Video description coming soon.

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/Q8jP3jMaoUc?si=WzkINh1p_TeG-L57" title="YouTube embed: 'Quick Nav' test"  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />

## Some Accessibility Issues

1. **SC 1.1.1 Non-text Content (Level A):** The charts tested do not have a text alternative. The only information presented by a screen reader is axis text labels and (sometimes) the tooltip content is reachable.
1. **SC 1.3.1 Info and Relationships (Level A):** When a legend is configured, it has no directly coded relationship to the chart. Since it is placed in the DOM after the chart with `role="application"` there is no inferred relationship. Tooltips are also after the `role="application"` element, so their content cannot be presented by screen readers without moving through the rest of the chart content.
1. **SC 1.4.1 Use of Color (Level A):** Color is currently the only way someone can visually distinguish data in the charts. I have not found documentation for how to make these charts visually accessible with strategies like monochrome palettes, line styles, pattern fills, or extra labels. The tooltips can help, but only if they represent one piece of data at a time. In the videos above, each tooltip represents two bars.
1. **SC 1.4.13 Content on Hover or Focus (Level AA):** The tooltips can be dismissed with the <kbd>ESCAPE</kbd> key, but they are not hoverable or persistent. This prevents _many_ people from perceiving and understanding the tooltip content. They may also accidentally make the tooltip disappear with the slightest cursor movement.

## In Summary

In my quick-ish testing, I found multiple critical accessibility issues with the Chart component. The "keyboard access" claim in the documentation is mostly accurate. The "screen reader support" claim is false. No information is presented about the data by a screen reader when using the left or right arrow keys to navigate the charts.

The documentation also does not describe how keyboard or screen reader interactions _should_ work, which I find irresponsible considering the bold marketing claims this library is "Accessible."

With great popularity comes great responsibility. Web accessibility is becoming more enforced by law and expectations of UI libraries are rising. Most library consumers will take "Accessible" at face value when they trust the maintainers or referrals. Since charts are an "advanced" accessibility topic, many likely don't know how to verify the claim.

As a person who relies on a multitude of accessibility "features" (I don't like the term "accessibility feature" but I can't think of an alternative), it's discouraging to see a popular UI library miss key aspects. When the marketing says "Accessible" but neither the documentation nor the functionality backs it up, it diminishes my trust and the library's credibility.

If the documentation demonstrated effort in it, I would believe accessibility is a priority. But based on my test results, the library's popularity, and my lived experiences: I don't see enough evidence to feel that accessibility is treated as seriously as it needs to be. It feels performative. I'd love for that perspective to change.

## Related Resources

### From the Do No Harm Guide: Centering Accessibility in Data Visualization

- [Summary by Urban Institute](https://www.urban.org/research/publication/do-no-harm-guide-centering-accessibility-data-visualization)
- [Report as PDF](https://www.urban.org/sites/default/files/2022-12/Do%20No%20Harm%20Guide%20Centering%20Accessibility%20in%20Data%20Visualization.pdf)
- Chapter 5: Coding Accessible Data Visualisations (by [Léonie Watson](https://tink.uk/))
- Chapter 6: Creating Better Screen Reader Experiences (by [Sarah Fossheim](https://fossheim.io/))

### From the Web Content Accessibility Guidelines 2.2

- [SC 1.1.1 Non-text Content (Level A)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html)
- [SC 1.3.1 Info and Relationships (Level A)](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships)
- [SC 1.4.1 Use of Color (Level A)](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html)
- [SC 1.4.13 Content on Hover or Focus (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html)
- [Understanding "Text Alternatives"](https://www.w3.org/WAI/WCAG22/Understanding/conformance#text-alternatives)

### By Léonie Watson

- [Accessible SVG line graphs](https://tink.uk/accessible-svg-line-graphs/)
- [Accessible SVG tables](https://tink.uk/accessible-svg-tables/)
- [Accessible SVG flowcharts](https://tink.uk/accessible-svg-flowcharts/)


My personal analysis after a few keyboard & screen reader tests.

A Quick-ish Accessibility Review: shadcn/ui Charts


## TL;DR

This bookmarklet can help you visually check how well a webpage handles text being resized to 200% of the base/default size. It can also help you test for loss of content when checking compliance for [WCAG 2.2 Success Criterion 1.4.10 Reflow](https://www.w3.org/TR/WCAG22/#reflow).

To add the bookmarklet to your preferred browser:

1. Create a new bookmark
2. Give it a good name (maybe "Toggle text zoom")
3. Copy-and-paste the following code for the URL

```js
javascript: (function () {
  const htmlElement = document.querySelector('html');
  const currentFontSize = htmlElement.style.getPropertyValue('font-size');
  const isZoomed = currentFontSize === '200%';
  const newFontSize = isZoomed ? null : '200%';
  htmlElement.style.setProperty('font-size', newFontSize);
})();
```

Disclaimer: This is experimental and should be used at your own risk! If a webpage is already coded to set the CSS `font-size` property on the `<html>` element, this bookmarklet probably won't work as intended.

## Does WCAG have text size requirements?

The [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG22/) has one Success Criterion criterion in particular that talks about text size. [WCAG 2.2 Success Criterion 1.4.4 Resize Text](https://www.w3.org/TR/WCAG22/#resize-text) says:

> Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality.

## Text resizing is not the same as browser zoom

You might be thinking, "But when I zoom in my browser to 200% the button text looks fine!" This is probably a common misconception with this Success Criterion. I definitely didn't know for a while that browser zoom is only part of the story!

Digging deeper using the [Understanding SC 1.4.4: Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) docs, it says we (the "authors") have to handle the case when a user only increases the size of their text since their browser (or some other "user agent") might not have zoom capability.

The docs say:

> If the user agent doesn't provide zoom functionality but does let the user change the text size, the author is responsible for ensuring that the content remains usable when the text is resized.

This Success Criterion is one reason why it's good practice to use `rem` units for the CSS `font-size` property and no units for the `line-height` property. Text must be resizeable up to 200% without a mechanism like browser zoom.

## How do I test 200% text size?

The easiest way I've found to test text-only zoom is by setting `font-size: 200%` on the `<html>` element for a web page. This can be done a few ways:

1. Manually adding the CSS property in browser dev tools
2. Running some JavaScript in the browser console
3. Putting the JavaScript in a bookmarklet and running it with one click

I prefer option 3 the most because it's just one click and it's a more accurate user experience test since I can keep the browser dev tools panel closed.

My bookmarklet is set up to **_toggle_** the `font-size: 200%` setting on the `<html>` element when the bookmark is clicked. It checks if the current `font-size` value is already set to `200%`, and adds or removes it based on that check.

To add the bookmarklet to your preferred browser:

1. Create a new bookmark
2. Give it a good name (maybe "Toggle text zoom")
3. Copy-and-paste the following code for the URL

```js
javascript: (function () {
  const htmlElement = document.querySelector('html');
  const currentFontSize = htmlElement.style.getPropertyValue('font-size');
  const isZoomed = currentFontSize === '200%';
  const newFontSize = isZoomed ? null : '200%';
  htmlElement.style.setProperty('font-size', newFontSize);
})();
```


Quickly test your 'loss of content' risk when text is resized.

An Accessibility Bookmarklet for Testing 200% Text Size


## Why not?

Despite some web design tools specifying CSS `height` values for elements like buttons, setting `height` or `max-height` can actually put you at risk for failing [WCAG 2.2 Success Criterion 1.4.4 Resize Text](https://www.w3.org/TR/WCAG22/#resize-text).

This Success Criterion requires:

> Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality.

When using fixed values for CSS properties that affect an element's computed height and width, text inside of the element will get cut off when text size is increased.

## Not convinced?

You might be thinking, "But when I zoom in my browser to 200% the button text looks fine!" This is probably a common misconception with this Success Criterion. I definitely didn't know for a while that browser zoom is only part of the story!

Digging deeper using the [Understanding SC 1.4.4: Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) docs, it says we (the "authors") have to handle the case when a user only increases the size of their text since their browser (or some other "user agent") might not have zoom capability.

The docs say:

> If the user agent doesn't provide zoom functionality but does let the user change the text size, the author is responsible for ensuring that the content remains usable when the text is resized.

This Success Criterion is one reason why it's good practice to use `rem` units for the CSS `font-size` property and no units for the `line-height` property. Text **must** be resizeable up to 200% without a mechanism like browser zoom.

But how? It's easier to handle than you might think!

## Code demos

_Note: For the purpose of these demos, please pretend that we're using `rem` units for `font-size`. I use `px` units here so as to not inherit the base font styles from my website._

### Demo 1

First, let's take a look at what happens when text size is increased while using fixed values for `font-size`, `height`, `line-height`, and `width`. Before the text size is increased, the button looks great! Not so great after increasing the text size though.

<CallOut id="demo-1a" title="Before text size is increased" type="example">

<button style={{
  alignItems: 'center',
  appearance: 'none',
  border: '1px solid black',
  display: 'flex',
  fontFamily: 'Arial',
  fontSize: '16px',
  height: '36px',
  justifyContent: 'center',
  lineHeight: '18px',
  overflow: 'hidden',
  textWrap: 'nowrap',
  width: '82px',
}}>
delete all
</button>

```html
<button style="font-size: 16px; height: 36px; line-height: 18px; width: 82px;">
  delete all
</button>
```

</CallOut>

<CallOut id="demo-1b" title="After text size is increased" type="example">

<button style={{
  alignItems: 'center',
  appearance: 'none',
  border: '1px solid black',
  display: 'flex',
  fontFamily: 'Arial',
  fontSize: '32px',
  height: '36px',
  justifyContent: 'center',
  lineHeight: '18px',
  overflow: 'hidden',
  textWrap: 'nowrap',
  width: '82px',
}}>
delete all
</button>

```html
<button style="font-size: 32px; height: 36px; line-height: 18px; width: 82px;">
  delete all
</button>
```

</CallOut>

### Demo 2

Now let's take the same code and try using no units for `line-height`, and `padding` for affecting the button's `height` and `width`. We shouldn't see the text get cut off at all when the text size is doubled.

<CallOut id="demo-2a" title="Demo 2a: Before text size is increased" type="example">

<button style={{
  appearance: "none",
  border: "1px solid black",
  fontFamily: "Arial",
  fontSize: "16px",
  lineHeight: "1.125",
  overflow: "hidden",
  padding: "8px",
  textWrap: "nowrap",
}}>
delete all
</button>

```html
<button style="font-size: 16px; line-height: 1.125; padding: 8px;">
  delete all
</button>
```

</CallOut>

<CallOut id="demo-2b" title="Demo 2b: After text size is increased" type="example">

<button style={{
  appearance: "none",
  border: "1px solid black",
  fontFamily: "Arial",
  fontSize: "32px",
  lineHeight: "1.125",
  overflow: "hidden",
  padding: "8px",
  textWrap: "nowrap",
}}>
delete all
</button>

```html
<button style="font-size: 32px; line-height: 1.125; padding: 8px;">
  delete all
</button>
```

</CallOut>

## Another approach

One technique the Understanding docs for note is [C28: Specifying the size of text containers using em units](https://www.w3.org/WAI/WCAG22/Techniques/css/C28). In my experience I've found this approach harder to maintain as viewport sizes shrink.

Think of a mobile device with large text size settings. It's possible the text container sized with `em` units would end up wider than the viewport. If the text is cut off by the device size, that means we're at risk for failing not one but two WCAG 2.2 Success Criterion:

- [SC 1.4.4 Resize Text](https://www.w3.org/TR/WCAG22/#resize-text)
- [SC 1.4.10 Reflow](https://www.w3.org/TR/WCAG22/#reflow)

One option for preventing this while using Technique C28 could be to leverage a CSS property like `max-width`, but personally I prefer to use the least number of CSS properties possible (for lower long term maintenance cost). Instead of using `width` and `max-width` it's likely we can just use `padding` and let the browser do it's default magic for making elements fit in a viewport.


Fixed heights and widths risk 'loss of content' when text is resized.

Don't Use Fixed CSS height or width on Buttons, Links, or Any Other Text Containers


The `aria-label` property can be extremely useful when used correctly. When used incorrectly, it can wreak havoc on speech-input user experiences. It's an easy mistake to make and luckily it's pretty easy to fix!

For the **TL;DR**: jump to [How do I fix mismatched `aria-label`s and visual labels?](#how-do-i-fix-mismatched-aria-labels-and-visual-labels)

## Table of Contents

1. [A note about Voice Control](#a-note-about-voice-control)
1. [What is the `aria-label` property?](#what-is-the-aria-label-property)
1. [Why does `aria-label` need to match the visible label?](#why-does-aria-label-need-to-match-the-visible-label)
1. [What happens when `aria-label` doesn't match the visible label?](#what-happens-when-aria-label-doesnt-match-the-visible-label)
1. [Are there other users that benefit from `aria-label` matching the visible label?](#are-there-other-users-that-benefit-from-aria-label-matching-the-visible-label)
1. [How do I fix mismatched `aria-label`s and visual labels?](#how-do-i-fix-mismatched-aria-labels-and-visual-labels)
1. [Related Resources](#related-resources)
1. [Article Updates](#article-updates)

## A note about Voice Control

As of my understanding in July 2024, Apple's Voice Control requires its users to say an element's _entire_ Accessible Name to interact with it. So while [SC 2.5.3: Label in Name](https://www.w3.org/TR/WCAG21/#label-in-name) only states the Accessible Name must _contain_ the label, it's best to make the visible label and Accessible Name match exactly.

Thank you [Tori Clark for tweeting this info to me](https://x.com/toriclarka11y/status/1652468409328627717) back in April of 2023. Sorry it took so long to add here!

![Nothing missed! The only thing that might be worth delineating more is that Voice Control demands the -full- accessible labels be spoken, whereas partial labels work great with Dragon and Windows Speech Recognition as long as it's early in the accessible name/label.](https://res.cloudinary.com/ashleemboyer/image/upload/article-images/ToriClarkTweet-20230429_m2tgph.png)

## What is the `aria-label` property?

As defined by the WAI-ARIA 1.2 standards, [the `aria-label` property](https://www.w3.org/TR/wai-aria-1.2/#aria-label) "defines a string value that labels the current element". It has the same purpose as [the `aria-labelledby` property](https://www.w3.org/TR/wai-aria-1.2/#aria-labelledby), which references another element that labels the current element. The purpose of both of these properties is to provide an [Accessible Name](https://www.w3.org/TR/accname-1.1/#dfn-accessible-name) of the current element.

Related to these properties is the `aria-describedby` property, which references another element that describes the current element. The purpose of this property is to provide an [Accessible Description](https://www.w3.org/TR/accname-1.1/#dfn-accessible-description) for the current element. The Accessible Name should be concise, and the Accessible Description should be more verbose and complement the Accessible Name.

The Accessible Name is part of what screen readers use to announce elements to a user when they come into focus. A `<button>` with no `aria-label` and plain text between its opening and closing tags would have an Accessible Name that matches its plain text. That same `<button>` can have its Accessible Name overridden with something completely different using the `aria-label` property.

Use the next two example code snippets to compare how the same button sounds with and without an `aria-label`.

<CallOut id="example-1" title="Example 1: <button> with no aria-label" type="example">

The code:

```html
<button>OK</button>
```

The output:

<br />
<button>OK</button>

</CallOut>

<CallOut id="example-2" title="Example 2: <button> with an aria-label" type="example">

The code:

```html
<button aria-label="Confirm selection">OK</button>
```

The output:

<br />
<button aria-label="Confirm selection">OK</button>

</CallOut>

## Why does `aria-label` need to match the visible label?

First of all, an `aria-label` must match its element's visible label because there is a Level A WCAG Success Criterion that says so. [SC 2.5.3: Label in Name](https://www.w3.org/TR/WCAG21/#label-in-name) says:

> For user interface components with labels that include text or images of text, the name contains the text that is presented visually.

This means that the Accessible Name computed for an element should contain the text of the element's visual label. One best practice for this is to have the Accessible Name start with the visual label's text. So if a link contains the text "Learn more" and the author of that link wants to include more information about the link's purpose in the `aria-label`, a good practice is to start the `aria-label` with "Learn more".

If you're like me and my ADHD brain, you might need a little more reasoning than "the rules say so" to motivate you to follow the rules. A lot of people don't like being told what to do, and that's fine!

So why do we need to follow Success Criterion 2.5.3? It partially has to do with speech recognition technology. As it turns out, the Accessible Name for elements is how speech-input users can interact with elements in a web page.

Referencing our two previous examples:

- A speech-input user can activate the button from [Example 1](#example-1) by saying "Click OK". This is because the Accessible Name for that button is "OK".
- A speech-input user cannot activate the button in [Example 2](#example-2) in the same way. This is because the Accessible Name for that button is "Confirm selection". If a speech-input user wanted to activate this button, they would have to say "Click confirm selection".

For speech-input users who rely on visual labels to come up with voice commands, there is no way for them to know before speaking a command if the Accessible Name of an element differs from its visual label. They will have to speak a command and find out if it does or does not work. If a command doesn't work, they may retry a couple of times. If the command does not work at all because the Accessible Name doesn't match the visual label, their energy has been wasted and they're also stuck.

## What happens when `aria-label` doesn't match the visible label?

As I wrote this article, I started to learn about Voice Control on Mac. I wanted to see if I could find a real-world example of speech-input navigation being broken due to mismatched visual labels and accessible names. I found a couple of examples right on the Twitter home page.

Unfortunately, more than half of the main navigation links have accessible names that don't match their visual labels. Even in the cases where a link's `aria-label` began with the text in the visual label, I was not successful in activating those links with speech input. I made countless attempts.

- Home: The `aria-label` for this link is dynamic. If there are unread tweets in a user's feed, then the `aria-label` reads "Home (New unread Tweets)". The "Click Home" command only activates this link if there are no unread tweets.
- Explore: The `aria-label` for this link is "Search and explore". Saying "Click Explore" does not activate this link.
- Notifications: The `aria-label` for this link is dynamic. If a user has 2 notifications, for example, the `aria-label` is "Notifications (2 unread notifications)". The "Click Notifications" command only activates this link if a user has 0 unread notifications.
- Messages: The `aria-label` for this link is dynamic. If a user has unread messages from one other user, for example, the `aria-label` is "Direct Messages (1 unread conversation)". If there are no unread messages, the `aria-label` is "Direct Messages". The "Click messages" command does not ever work.

Here's a quick demo of me trying to activate the "Messages" link that shows on the home page of Twitter:

<iframe
  title="Voice Control Demo - Twitter Messages link"
  width="100%"
  height="350"
  src="https://www.youtube-nocookie.com/embed/FBiKOt-ipO0"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

## Are there other users that benefit from `aria-label` matching the visible label?

This article primarily focuses on the sighted speech-input user's experience, but there are other users affected by this issue as well. Think of a sighted screen reader user that comes across the `<button>` element in [Example 2](#example-2). It is presented by their screen reader as "Confirm selection, button", but the text in the button says "OK".

This can be a very confusing and stressful experience for the user. How can they be certain the issue is with the website and not their own action? We're imposing an extra cognitive load on the user to process the mismatched audio and visual experiences. There is also extra cognitive load required to first memorize the behavior, and then recall it the next time they come across the element.

It's not necessary or kind to do this to users. It's energy-draining, and energy is an extremely limited resource for all kinds of people who rely on accessible interfaces.

## How do I fix mismatched `aria-label`s and visual labels?

Now that you know mismatching `aria-label` and visual labels is harmful to speech-input users, how do you go about preventing that harm? First, I'd recommend reading [Playing with state](https://sarahmhigley.com/writing/playing-with-state/) by Sarah Higley and [Be Careful with Dynamic Accessible Names](https://adrianroselli.com/2020/12/be-careful-with-dynamic-accessible-names.html) by Adrian Roselli.

Second, think about whether or not you need to provide an `aria-label` for the element that differs from its visual label. Some cases that come to mind:

- Are there duplicate visual labels?
  - Your markup can generally be improved by ensuring all visual labels are unique. This is beneficial for screen reader navigation.
  - The speech recognition technology probably has a way to help the user choose which element they want. With Voice Control on Mac, a number appears next to the elements with matching Accessible Names after the command is spoken. Then you're able to say the number of the element you want to activate.
- Is the content of the element plain text? Omit the `aria-label` property. The computed accessible name for the element will be its text content.
- Is the element a toggle button? Reference the [Playing with state](https://sarahmhigley.com/writing/playing-with-state/) article I mentioned and also check out the [Toggle Buttons](https://inclusive-components.design/toggle-button/) writeup from Inclusive Components. The `aria-pressed` property better suits your needs than a dynamic `aria-label`.

After you've spent time thinking thoroughly about your `aria-label`s and visual labels, make the updates and **test them with your users**. It's hard for us to know if something is usable if it doesn't intersect with our own needs. The only experiences we can truly be experts in are our own. Don't miss the step where you get your information from the source of truth: your users with expertise in their lived experiences.

## Related Resources

- [Designing and coding for voice](https://www.briandeconinck.com/designing-coding-voice/) [Brian DeConinck]
- [Tori Clark talks about visible labels and Dragon](https://a11yrules.com/podcast/tori-clark-talks-about-visible-labels-and-dragon/) [A11y Rules Podcast]
- [Accessible Icon Buttons](https://www.sarasoueidan.com/blog/accessible-icon-buttons/) [Sara Soueidan]
- [Buttons with icons and text](https://www.tempertemper.net/blog/buttons-with-icons-and-text) [Martin Underhill]
- [What I wish was in WCAG: prohibit icon-only buttons](https://www.tempertemper.net/blog/what-i-wish-was-in-wcag-prohibit-icon-only-buttons) [Martin Underhill]
- [Testing with speech recognition](https://www.tpgi.com/testing-with-speech-recognition/) [TPGi]
- [Perspective Video: Speech Recognition](https://www.w3.org/WAI/perspective-videos/voice/) [Web Accessibility Initiative]
- [Stories of Web Users: Ade's Story](https://www.w3.org/WAI/people-use-web/user-stories/story-one/) [Web Accessibility Initiative]
- [Use Voice Control on your Mac](https://support.apple.com/en-us/102225) [Apple Support]
- [Use Voice Control on your iPhone, iPad, or iPod touch](https://support.apple.com/en-us/111778) [Apple Support]
- [YouTube Playlist: Dragon in Action](https://www.youtube.com/watch?v=FXzXiOl7O4U&list=PLRFp5KqXtQ6yFAnF0DPUJYRbXnaTjMSQE&index=1) [Nuance Communications Channel]

## Article Updates

1. **<time dateTime="2022-09-01">September 9, 2022</time>:** First published.
1. **<time dateTime="2023-04-24">April 24, 2023</time>:** Added Related Resources section with one link (Designing and coding for voice).
1. **<time dateTime="2024-07-09">July 9, 2024</time>:**
   - Added TL;DR jump link.
   - Added [Table of Contents](#table-of-contents) section.
   - Added [a note about Voice Control](#a-note-about-voice-control).
   - Added 10 links to the [Related Resources](#related-resources) section.


Users suffer when the accessible name of an element doesn’t match its visual label.

Posts Related to the "wcag" Tag