
## 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 are CSS margin and padding so closely related?

The CSS [margin](https://developer.mozilla.org/en-US/docs/Web/CSS/margin#values) and [padding](https://developer.mozilla.org/en-US/docs/Web/CSS/padding#values) properties are often talked about together for two reasons:

1. They both affect whitespace and sit right next to each other in the [CSS Box Model](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/The_box_model), only separated by a border if one's present.
2. They accept nearly the exact same CSS data types for their values: `length` and `percentage`. (`margin` also accepts `auto`, but that's not important for what we're discussing here.)

## What are the length and percentage CSS data types?

[CSS length](https://developer.mozilla.org/en-US/docs/Web/CSS/length) is one type of a distance value. [CSS percentages](https://developer.mozilla.org/en-US/docs/Web/CSS/percentage) are similar to length, but the difference is that they're always a fraction of something else in a page depending on what property they're being used with. Lengths can either be _absolute_ or _relative_.

## What's the difference between absolute and relative units?

CSS provides us two types of units so we can build flexible websites that work across all kinds of devices and configurations.

- [**absolute length units**](https://developer.mozilla.org/en-US/docs/Web/CSS/length#absolute_length_units) are always the same, and not based on anything else in a page
- **relative length units** units can change, and are based on [font](https://developer.mozilla.org/en-US/docs/Web/CSS/length#relative_length_units_based_on_font) and [viewport](https://developer.mozilla.org/en-US/docs/Web/CSS/length#relative_length_units_based_on_viewport)

## How do I know when to use absolute or relative CSS units?

Most people don't like their questions answered with a question, but that's how I feel like breaking this down right now. (Sorry!!)

When you're deciding between absolute or relative CSS units for a particular CSS property, you need to think about what a user is trying to do.

You may already be familiar with **relative length units** when it comes to text size. It's best practice to use `rem` units for the `font-size` property, because it enables users to customize their viewing experience with settings on their personal device.

**Relative length units** are also commonly used for changing how a page looks based on a user's viewport size. It's how we go about [implementing responsive designs](https://ashleemboyer.com/blog/tags/responsive-design) that will work no matter what device, window size, page zoom, or text size a user has.

So what user actions are we designing for when we use **relative length units**?

- Increasing text size settings
- Resizing a browser window
- Zooming in or zooming out of a page
- Reading from a mobile device

In all of these situations, what does a user care about most? The content, or the spacing between the content? Which of these two things are vital for understanding the web page?

## Why shouldn't I use relative units for margin, padding, or other spacing techniques?

When a user is customizing their viewing experience, they thing that's most important to them and their task at hand is **the content**. Spacing isn't often vital for a user to perform their task, so it doesn't need to grow or scale at the same rate as the content itself.

When spacing between content grows, it eats up vital real estate and becomes harder to manage. You probably know the pain of horizontal spacing if you've worked on a site long enough to add multiple main navigation links over time. You run out of space at double the rate if you scale `margin` and `padding` exactly like text size!

In terms of vertical spacing, you also end up making a user's task harder to complete. There's nothing you can do about text that has to wrap to the next line based on limited horizontal space, but you don't want to make pages _even taller_ because your vertical spacing grows with your text size.

Tall pages mean more scrolling and work for a user that just wants to read content differently, and they'll also be even more limited at how much content they can see at one time.

## Code demo: the difference between absolute and relative units for margin and padding

I'm going to "pick on" a page from Subway's website because it's the first one that came to mind where I've for sure experienced this issue. I don't have anything against them or the developers that made this website! It's just helpful to see a real world example, and it's easier for me than to come up with my own.

<CallOut
  title="Note: This demo's webpage has multiple accessibility issues."
  type="disclaimer"
>

This webpage has other issues besides using `rem` units for `margin` and `padding`. My goal in this demonstration is to show how this approach affects **_content height_**, and thus scrolling and readability. There are still reflow issues that occur on the page that require a little bit more code in addition to swapping `rem` units for `px`.

</CallOut>

### Before increasing text size

At the time of writing (November 2nd, 2023), here's the basic view of one page without increasing text size. At a high level, it has:

- a navigation header with the logo, multiple links, and a few buttons
- a two-column call to action with large text, a description, button, and a Christmas themed graphic
- a three-column breakdown with additional information about the product being sold on the page

<img
  alt=""
  src="https://res.cloudinary.com/ashleemboyer/image/upload/v1702832787/article-images/SubwayBeforeTextSizeIncrease_a9dkuw.png"
/>

### After increasing text size

To test what happens with only a text size increase, I can add one CSS property to the main `<html>` element on the page: `font-size: 200%;`. This works by doubling whatever base font size the website is using, and because they use `rem` units for actually sizing text.

<CallOut
  title="Related WCAG: Success Criteria 1.4.4 Resize Text and 1.4.10 Reflow"
  type="idea"
>

Curious about this `font-size: 200%;` approach? I break down the WCAG requirements related to text resize and this testing approach in a separate post.

👉🏻 Set yourself up for text-size success with one of my favorite custom bookmarklets: [An Accessibility Bookmarklet for Testing 200% Text Size](https://ashleemboyer.com/blog/an-accessibility-bookmarklet-for-testing-200-percent-text-size)

</CallOut>

Unfortunately, they also use `rem` units for `margin` and `padding` in most elements. In the next screen recording, we can see that:

- The navigation header is now extremely tall, taking up almost half of the window height and also covering up the next section of content.
- Less than half of the navigation header content is visible, because most of it is overflowing off the righthand side of the window.
- The two-column call to action section is still two columns, not leaving much horizontal space for all the text it has.
- Within the text column of the call to action section, the space around the text is larger, leaving even less horizontal space to read it. The large text is showing about one word per line, and the smaller text is only showing a couple words per line.

<iframe
  title="Subway's website with increased text size & rem units for margin and padding"
  width="100%"
  height="400px"
  src="https://www.youtube-nocookie.com/embed/4R8t8Z1H4jc?si=DKw62HBVEFXtnI_T"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  allowFullScreen
></iframe>

### After updating to px units

To show what this webpage would look like if it used `px` units for `margin` and `padding` instead of `rem` units, I inspected the HTML and CSS using my browser devtools and overwrote some of the CSS values. As we can see in the next screen recording:

- The navigation header still has content cut off to the right but it's much shorter, meaning we have more space to see the main content on the page.
- Since we can see more content at once on the page, the content is easier to understand because there's more immediate context to get information from while reading.
- In what was the two-column call-to-action, I adjusted the padding around and between groups of text to no longer scale, giving more horizontal space to show the text.
- I also made the two-column call-to-action just one column to decrease the height of the text portion. This demonstrates a large benefit of making the media query for this section use `rem` units rather than `px` units (article on this approach coming soon).

<iframe
  title="Subway's website with increased text size & px units for margin and padding"
  width="100%"
  height="400px"
  src="https://www.youtube-nocookie.com/embed/Q_9gOkbWFno?si=LZN1aoiyXnKNnvSz"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  allowFullScreen
></iframe>

## How else can I make my responsive design accessible?

It's your lucky day! I've been working on an informal series about accessible responsive design.

- Recently posted: [Don't Use Fixed CSS height or width on Buttons, Links, or Any Other Text Containers](https://ashleemboyer.com/blog/don-t-use-fixed-css-height-or-width-on-text-containers)
- Currently in-progress and coming soon: Why You Should Use `rem` instead of `px` Units in CSS Media Queries


When users increase their text size, they're not trying to make the space around text bigger.

Why You Should Use px Units for margin, padding, & Other Spacing Techniques


## 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


If you've been on tech twitter in the past week, you might've seen a TypeScript debate that seemingly came out of nowhere. Well, it came from news that [Turbo 8 is dropping TypeScript](https://web.archive.org/web/20230909190042/https://world.hey.com/dhh/turbo-8-is-dropping-typescript-70165c01). There has been all kinds of commentary on this news, but there's one that's almost always left out in discussions about developer tooling: developer accessibility.

Not enough people in software think of developer productivity as effectively being the same thing as developer accessibility. So let's talk about it! Prepare to go through some of the features of TypeScript that can be especially helpful for disabled and/or neurodivergent developers. I'm listing them in alphabetical order.

_If you think something is missing below or want to share the accessibility benefits you experience with TypeScript, [send me a tweet](https://twitter.com/ashleemboyer) or [email me](mailto:hello@ashleemboyer.com)!_

## Code editor tools (code completion, hover tooltips, etc.)

The code editor tools that come with TypeScript are my favorite part of TypeScript. Code completion is probably the top one for me. I can be very easily distracted some days (ADHD) or I might be mentally tired from fighting through distractions. Code completion ends up being a tiny _helpful_ distraction. It keeps me on task and gives me all the options I have at hand as I type. I don't I have to remember every single detail of whatever code I'm working with. TypeScript does it for me and gives me little reminders. It's also a lot less typing, which my hands and brain are very grateful for on high pain days.

The hover tooltips that appear on top of code are also helpful for reducing cognitive overload and increasing productivity. It reduces the scope of understanding a codebase at a high level, rather than having to memorize so many small details and staying on top of changes to them. For example: It's not important to memorize every possible property of an object that fits under your business logic. Those can change easily at any time and without you knowing if you work on a larger team. It's impossible to keep track of everything yourself.

## Maintainable, built-in documentation

I've worked on all sorts of projects in my career already. From brand-new to several years old, from small to medium sized teams - they all go through the same problems in different flavors. One big problem every development team faces is documentation maintenance. I personally _love_ writing documentation, and I still think making it maintainable is the hardest part.

It can't just be about one person's process or system for maintaining documentation, because we all think and work differently. Finding a balance across a team's differing working styles is incredibly important for healthy collaboration. I've found that coupling different types of tasks together with the main task you already have the hang of is fairly successful.

For example: It can be easier to remember to update documentation when it's a co-located code comment vs. when it's in a separate Markdown file. This is because it's right next to where you're already working. It's less time than figuring out where the existing documentation might be, or trying to decide where to put new documentation.

What's even better is that TypeScript is _functional_ co-located documentation. When you make a change to a type or interface (which is already part of the code writing process), the documentation is getting updated at the same time because the types are both code and documentation. You may need to update some neighboring code comments as well, but there's still less steps involved in keeping your codebase's documentation up to date.

## Immediate feedback

TypeScript provides feedback on your code at compile time, meaning you don't always have to wait until you run your code to see if it doesn't work. If you're writing code that needs to be tested in a browser, switching from your code editor to your browser to do so is a mental context switch.

These moments can carry large risk for distraction depending on your ability to focus at the time. They can also be exhausting after a while if you have to fight your brain each time to force it to stay focused. Since TypeScript can help reduce the occurrence of some runtime errors before you even leave your code editor, that means less of these context-switching moments, so less risk for distractions and less energy wasted on what's likely common and minor issues.

Immediate feedback also reduces the cognitive load needed to figure out why a likely common runtime error happened. Who wants to spend time debugging typos or digging into source code to figure out why you couldn't access a property on an object that doesn't actually exist on it? Don't get me wrong, reading code can interesting and insightful. But if I'm trying to write code efficiently, I don't want to read other code that much. Working smarter (not harder) means making computers do the heavy lifting for us wherever possible. 😉

## Onboarding

Onboarding to a new codebase regardless of its age or size is no small task. The questions that come to mind in the process are endless, and that can get overwhelming and discouraging fast. It's also very time consuming, and it can be scary building up the confidence to ask questions to your peers when you're new and getting to know them.

> What tooling does it use? What tooling does it _not_ use that you might be accustomed to relying on? What standards does it follow? Where is the documentation (if any)? Who do you ask questions to? Where can you learn the context of various decisions? What areas are people too afraid to change? Does it use camel case or snake case? What ESLint rules does it have (if any) and why? How do different areas connect to the business logic? What is the business logic? Is this particular business logic still relevant? Why is this code here if it doesn't look like it's used? Does the person that wrote this still work here? Why does the UI do this? Who asked for this feature? Where is this function defined? How was this data computed before it was passed to this function? ...

With TypeScript working as built-in documentation and also having helpful code editor tools for jumping to definitions or showing additional information through hover tooltips, there's decreased cognitive load needed for navigating a codebase. You don't have to guess where to find documentation or definitions. You also don't always have to leave the current file you're in. And when you start writing code, you're given suggestions of what's possible for you to do as you write. You don't have to pause, leave the current file or section of code, or remember what you were doing and where.

TypeScript helps you start writing code that does something more quickly, which is beneficial for the contributors or consumers of a codebase. But this isn't just about the developers that build a product. Developers that are using a software product are going to **_keep using it_** if it helps them do their jobs quickly and successfully. Onboarding developers as users is an important facet of building software as a product.


TypeScript can be a helpful tool for disabled and/or neurodivergent developers.

How TypeScript Can Improve Developer Accessibility


This isn't a long post, as there's not much to say other than "Yes, Deaf People Can Listen to Music". Deafness is a spectrum and doesn't automatically mean someone has zero hearing. Disability (which is what I consider my deafnesss, but not all d/Deaf people do) is a spectrum.

Music and d/Deaf people have existed for the same amount time. We can experience music through sign language interpretation, lipreading, watching musicans perform to the beat, feeling vibrations, and for those of us that use assistive technology like hearing aids or cochlear implants, we can hear some parts of songs. Again, it's a spectrum. So even with assistive technology we still all have different levels of hearing.

Here are some resources you can use for further research:

- [How Do Deaf People Listen To Music? (American Sign Language Vlog) - Rikki Poynter - YouTube](https://youtu.be/nKrHhqOQ5mw)
- [How Do Deaf People Experience Music? - AJ+ - YouTube](https://youtu.be/dwqSuvFzDdI)
- [How Do Deaf People Experience Music - DITSignLanguageSoc - YouTube](https://youtu.be/fvuYTDhi0t0)
- [Deaf 101: How Do Deaf People Listen To Music? - National Deaf Center](https://nationaldeafcenter.org/resource-items/deaf-101-how-do-deaf-people-listen-to-music/)


Music is an art that can be experienced by anyone.

Yes, Deaf People Can Listen to Music


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.

Don’t Overwrite Visual Labels With `aria-label`

Despite being answered time and time again, the button vs. link question prevails.

Should I Use a Button or a Link?


If you've seen "a11y" floating around the web development space and you're not sure what it means or how to say it, you're absolutely not alone. Don't feel bad! Almost no one knows what it is until someone else tells them. I didn't know for a long time. I even created a tool that relies on the mispronunciation of it!

## What is a11y?

"A11y" is a numeronym or number-based word. It is composed of three parts:

- `"a"` - the first letter of the word "accessibility"
- `"11"` - the number of letters between the first and last letters of the word "accessibility"
- `"y"` - the last letter of the word "accessibility"

Numeronyms are very common in web development! Think of "K8s" (Kubernetes), "i18n" (internationalization), and "o11y" (observability) as a few of examples. Some of them have different pronunciations depending on how the number in the middle is pronounced in combination with the letters before and after it.

The way we pronounce "K8s" is different than the way we pronounce "a11y" because of how the numbers flow with the other letters. We _could_ pronounce "K8s" as "kay-eight-ess", but "keights" (see the word eight in the middle?) is a single syllable and a little easier to say.

## How is a11y pronounced?

So how do we pronounce "a11y"? We say "ay-eleven-why". Pronunciations like "al-ee" or "al-eye" don't quite fit like most other pronunciations of numeronyms because they're not saying the number in the middle at all. This isn't to say that all numeronyms are said the same way, but most that use this format follow this idea.

## Why use a11y instead of accessibility?

Numeronyms are often used when their original word is a lot of characters or difficult to pronounce. [According to Wikipedia](https://en.wikipedia.org/wiki/Numeronym), the first numeronym was created in the 1980s for a software account owner's surname because it was too long for the system to handle. "Accessibility" is 6 syllables whereas its numeronym is 1 less. That's not a huge amount of savings, but the phonetics of "a11y" are easier for many people to verbalize than "accessibility" because the there are less "harsh" syllables in comparison.

Numeronyms are also helpful where brevity is important, such as in tweets because Twitter enforces a character maximum. Since there are less characters to type, it can also be more efficient once you get used to using it. For me personally, it's also easier to remember how to spell!

## Do I have to a11y instead of accessibility?

Nope! If you like using the word "accessibility" more than you like using the "a11y" numeronym, please continue to do so. It's definitely a matter of preference and using one or the other does not make you more or less knowledgeable. If someone tells you otherwise, they are unfairly gatekeeping the topic of web accessibility. What truly matters is that you know what "a11y" means so you're not thrown off when you read it in other people's content.

Remember: everyone has different accessibility needs. Some people use "a11y" because it's more accessible to them. If "accessibility" is more accessible to you, that's totally acceptable!


The "a11y" numeronym, why it's important, and how to pronounce it

What the heck is "web a11y"?


Scroll-to-top buttons are great for pages that are long enough to require a few scrolls to read everything. They're even better for extremely long pages. Scrolling is a lot of work for some users, especially on a mobile device. We (website creators) can greatly reduce the amount of work it takes to scroll our pages with surprisingly little effort on our part.

One example is the [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.1), which is 140,923 pixels tall at the time of this writing. I'm not calling them out, it's just one of my favorite pages on the entire internet! [It's a great resource for making accessible custom components](https://ashleemboyer.com/my-favorite-resource-for-making-accessible-custom-components).

Making a scroll-to-top button and making it scroll smoothly is probably a lot easier than you think. It's definitely a lot easier than _I_ thought! The code bits I'm about to show are for React and SCSS, but you don't need to know either. The basic concepts here are for JavaScript and CSS. We'll also cover how to get rid of the smooth scrolling when it's an accessibility concern.The best part of this approach? It requires no focus management! <span aria-hidden>🎉</span>

## Prerequisites

If you don't already have one, you need to add a Skip Navigation Link to your site. It's a quick, easy win as well, and the instructions below reference the one I use on my site. Not sure how to do it? Then read my post on [How I Added a Skip Navigation Link to My Next.js Site](https://ashleemboyer.com/blog/how-i-added-a-skip-navigation-link-to-my-next-js-site)!

## The React Code

As you may have read in [my post about Skip Navigation Links](https://ashleemboyer.com/blog/how-i-added-a-skip-navigation-link-to-my-next-js-site#what-does-the-code-look-like), I use Next.js Per-Page Layouts to help me render repeated content, such as navigation links, on many pages. The layout I use for the navigation header is where I placed a Skip Navigation Link and Scroll-to-Top link. The code looks something like this:

```tsx
import styles from './base-layout.module.css';

const BaseLayout = ({ children }) => {
  return (
    <div>
      <a href="#main-content" id="skip-navigation-link">
        Skip Navigation
      </a>
      <SiteHeader />
      <main id="main-content" tabIndex={-1}>
        {children}
      </main>
      <a href="#skip-navigation-link">Back to Top</a>
      <SiteFooter />
    </div>
  );
};
```

What's important from this code:

1. The Scroll-to-Top link goes to the first focusable control on the page, which should be a Skip Navigation Link.
2. The `href` of the Scroll-top-Top link matches the `id` of the Skip Navigation Link.

## The SCSS Code

The code below takes an accessibility- and browser-support- first approach. Rather than making the default behavior for scrolling be smooth, an animation which can be physically harmful to some folks (including myself), it only applies smooth scrolling when two conditions are true:

1. The `prefers-reduced-motion` query is supported ([see the CanIUse.com page](https://caniuse.com/mdn-css_at-rules_media_prefers-reduced-motion))
2. The value of the setting is `no-preference` (which unfortunately is the default value)

```scss
html {
  @media (prefers-reduced-motion: no-preference) {
    scroll-behavior: smooth;
  }
}
```

One thing to keep in mind is that [`scroll-behavior` does not have full browser support](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior#browser_compatibility). At the time of writing, the feature is still in development for Safari.

## Conclusion

That's it! It really is just a few lines of code. After you add this, everyone will be able to quickly scroll to the top of your website. You've also made it so your site doesn't accidentally harm someone who can't tolerate animations! Well done. I am proud of you!


Adding a scroll-to-top button with smooth scrolling is as easy as adding a few lines of code.

Accessible, Smooth Scroll-to-top Buttons with Little Code


Accessibility can be pretty overwhelming at first. There are a lot of things to consider and it's really hard to figure out what you don't know when you're just starting out. I hope you find this short list useful to help your first dive into making accessible digital content. My focus is usually on websites, but a lot of this is good for things like mobile apps, ebooks, and slideshows, too!

## 1. Color Contrast

Ensuring you have a good contrast between text color and background color ensures nearly everyone can consume your content. People with vision disabilities (vision loss or color blindness) need high contrasting colors. Your minimum goal here is to meet contrast standards for normal and large sized text.

My favorite tool for this is the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/). You can input your foreground and background text colors and it will tell you how they fare under the WCAG level AA and level AAA standards.

![A screenshot of the WebAIM Contrast Checker in action. It shows the overall contrast ratio of two colors to the right of two inputs, and below that it shows whether the contrast passes level AA and AAA standards for both normal and large sized texts.](https://firebasestorage.googleapis.com/v0/b/ashleemboyer-2018.appspot.com/o/headers%2F2020%2F07%2F26-three-thigns%2FScreen%20Shot%202020-07-26%20at%209.53.28%20PM.png?alt=media&token=aa6423ce-f0b1-4b2d-b43d-bb23765d0c40)

## 2. Alternative Text

Alternative text is also important for people with vision disabilities. There are two ways you can go about alternative text depending on your platform.

When you're making a website by writing your own HTML, writing blog posts, or posting to social media sites like Twitter, you can add alt text to images. In HTML, make sure you're providing an `alt` attribute all `img` elements. When writing blog posts, a lot of blogging platforms will have a text input for you to provide alternative text. On Twitter, you can add alternative text as you're about to tweet an image or GIF.

The previous points are only going to be useful for people using a screen reader. These devices pick up those attributes to present images to the person consuming them. However, not all users with vision disabilities use screen readers. So, if you feel like you'd rather make your alternative text available for everyone, it's common practice to surround an image description in square brackets and preface it with "Image description", like this:

```
[Image description: ...]
```

As for actually writing the image descriptions, that's going to take some practice. Imagine you are sitting socially distanced from a friend and you want to show them a picture you've come across on your phone, but you'd have to break social distance to physically show them. How would you describe the image to them in one or two sentences?

## 3. Semantic HTML

This point is a little more technical, but also useful for folks that use blogging platforms that provide text editors. The main lesson for this section? Use the elements that we have been given for their intended uses.

- Need to display things in a list format? Use a bullet (`<ul>` element) or numbered list (`<ol>` element).
- Have a navigation menu at the top of your site? Use a `<nav>` element.
- Have an element that users can click on to perform an important action? PLEASE use a `<button>` element. 😁

Using semantic HTML elments is so important because they're already able to be presented by assistive devices without much addition. You're going to start adding ARIA roles and properties the minute you start using `<div>`s for `<button>`s, and if you don't know what you're doing there, you can severely and negatively impact a screen reader user's experience.

W3Schools has a great resource for [reading about and practicing with HTML semantic elements](https://www.w3schools.com/html/html5_semantic_elements.asp).


You'll leave this post with straightforward action items for making your digital content more accessible.

Three Starting Points for Making Accessible Digital Content


During the first stream in the accessible React component live coding series, we spun the wheel and it chose the breadcrumb component for us! While the component was extremely straightforward, I think it was a great one to kick off the series. Let's dive right in, shall we?

## Setup

You can skip this part if you already have your own React project set up. This section is for anyone who wants to follow the series with a fresh project.

1. Run `npx create-react-app <project-name>` in your terminal
2. Remove the `src/App.css` file
3. Replace your `src/App.js` file with this code:

```jsx
import React from 'react';

const App = () => <div>Hello, world!</div>;

export default App;
```

4. Rename `src/index.css` to `index.scss`
5. Update the reference to the file from 4 in `src/index.js`
6. Remove `src/logo.svg`
7. Run the app (`yarn start` or `npm start`)

Now, you should see a "Failed to compile" error in your browser and it should be because we haven't added the `node-sass` package to or project yet.

8. Run `yarn add node-sass` or `npm install node-sass` in the terminal you've been working in so far
9. Re-run your app (`yarn start` or `npm start`)

Your browser should say "Hello, world!" now. We're all set up!

## My process

1. Read through the WAI-ARIA Authoring Practices documentation
2. Create a minimal React component that says "Hello"
3. Flesh out the React component with the necessary HTML elements
4. Figure out what inputs (props) the React component needs
5. Add the necessary WAI-ARIA Roles, States, and Properties
6. Add keyboard interaction
7. Perform manual tests (listen with a screen reader, navigate with a keyboard, etc.)
8. Add automated tests
9. Write the documentation

## 1. The WAI-ARIA Authoring Practices Documentation

The first thing we have to do is read [the available documentation for this component](https://www.w3.org/TR/wai-aria-practices-1.1/#breadcrumb) on the WAI-ARIA Authoring Practices web page. There's not too much to this component.

> A breadcrumb trail consists of a list of links to the parent pages of the current page in hierarchical order. It helps users find their place within a website or web application. Breadcrumbs are often placed horizontally before a page's main content.

There's no keyboard interaction to add here since you can use the Tab and Shift+Tab keys by default to navigation through links. We just have to make sure we're using the correct HTML elements in our component and we have one ARIA state ([`aria-current`](https://www.w3.org/TR/wai-aria-1.1/#aria-current)) and one ARIA property ([`aria-label`](https://www.w3.org/TR/wai-aria-1.1/#aria-label)) to include as well.

## 2. A Minimal React Component

This series of blog posts will use the file structure I have laid out in my [`a11y-components`](https://www.w3.org/TR/wai-aria-1.1/#aria-current) GitLab repository. It looks a bit like this:

```
src/
  components/
    Button/
    Dialog/
    Listbox/
    ...
  App.js
```

Let's add a `Breadcrumb` folder under `components`. You need to create the `components` folder and add an `index.js` file to it if you followed the Setup section above. Then we need to add 5 files to the Breadcrumb folder:

- Breadcrumb.jsx
- Breadcrumb.module.scss
- Breadcrumb.test.js
- index.js
- README.md

### Breadcrumb.jsx

This file will have all of our React code. Let's start with something minimal to check if our setup is correct:

```jsx
import React from 'react';

const Breadcrumb = () => <h1>Breadcrumb works!</h1>;

export default Breadcrumb;
```

### Breadcrumb.module.scss

This file will hold all of our CSS. We'll wait to add anything here until we start building up the component.

### Breadcrumb.test.js

Don't forget to write tests! They're not only important for making sure your component works as expected, but also for making sure that future changes you make don't break existing behavior. We'll write these after we've finished the component.

### index.js

This file is for exporting everything we need from the Breadcrumb component so it can be used elsewhere in the application. More complex components might have multiple exports in this file but ours will stay simple for this component:

```jsx
export { default as Breadcrumb } from './Breadcrumb';
```

### README.md

This is where we'll document our component. It's important to detail a component's purpose and how to use it. We'll have 3 main sections: Properties, Accessibility, and Usage (examples). Let's also save this file for when the component is done.

### Test it out

First add the following to the `src/components/index.js` file:

```jsx
export { Breadcrumb } from './Breadcrumb';
```

Then update `src/App.js` to use the component:

```jsx
import React from 'react';

import { Breadcrumb } from './components';

const App = () => <Breadcrumb />;

export default App;
```

Check your browser. It should say "Breadcrumb works!" with an `<h1>` element.

## 3. Add HTML elements to the React Component

Now that our component has all its files created and we've got a minimal version of it working and showing in our browser, we can start building it out to specification. Let's head back over to [the documentation](https://www.w3.org/TR/wai-aria-practices-1.1/#breadcrumb) and see what elements we need to use. You should see an "Example" section for the widget and a single link to the example. Let's [go there](https://www.w3.org/TR/wai-aria-practices-1.1/examples/breadcrumb/index.html).

Under "Accessibility Features" we can see that we need a `<nav>` element to contain all of the links and that the links need to be structured in an ordered list (`<ol>`) component. Don't worry about how the elements need to be labeled just yet. We'll get to that in a few minutes.

Let's change what our Breadcrumb component renders first. We can hardcode the elements for now and then make the component more dynamic in the next step.

```jsx
<nav>
  <ol>
    <li>
      <a href="">Link 1</a>
    </li>
    <li>
      <a href="">Link 2</a>
    </li>
    <li>
      <a href="">Link 3</a>
    </li>
  </ol>
</nav>
```

Save your component and you should see something like the following in your browser:

```
1. Link 1
2. Link 2
3. Link 3
```

Yay! Now we need to style the list horizontally and add a separator between each link. We're going to do this in CSS so that screen readers don't pick them up and present them to users.

1. Import the SCSS file in `Breadcrumb.jsx`:

```jsx
import styles from './Breadcrumb.module.scss';
```

2. Give the `nav` element in the component a `className`:

```jsx
<nav className={styles.BreadcrumbContainer}>...</nav>
```

3. Add the code to `Breadcrumb.module.scss`:

```scss
.BreadcrumbContainer {
  padding: 12px;
  background-color: lightgray;
  text-align: left;

  ol {
    margin: 0;
    padding: 0;
    list-style: none;

    li {
      display: inline;
      margin: 0;
      padding: 0;

      a {
        color: black;
      }
    }
  }

  // The visual separators
  li + li::before {
    display: inline-block;
    margin: 0 12px;
    transform: rotate(15deg);
    border-right: 2px solid black;
    height: 0.8em;
    content: '';
  }
}
```

The links should be listed horizontally on a gray background have separators between each.

## 4. Add Props to the React Component

Let's make our component accept a list of links so it's dynamic and can be reused. It looks like each link has two pieces: a readable label and an `href`. We first need to update `src/App.js` and pass an array of links to the component like this:

```jsx
<Breadcrumb
  links={[
    {
      label: 'Link 1',
      href: '',
    },
    {
      label: 'Link 2',
      href: '',
    },
    {
      label: 'Link 3',
      href: '',
    },
  ]}
/>
```

Now we need to update the component to accept and use a prop called `links`.

```jsx
const Breadcrumb = ({ links }) => (
  <nav className={styles.BreadcrumbContainer}>
    <ol>
      {links.map((link) => (
        <li>
          <a href={link.href}>{link.label}</a>
        </li>
      ))}
    </ol>
  </nav>
);
```

When you look at the browser, it should look exactly as it did before this step if you're using the same links as you previously hardcoded.

## 5. WAI-ARIA Roles, States, and Properties

We have two ARIA attributes to discuss for this component: `aria-label` and `aria-current`.

### `aria-label`

This attribute describes the kind of navigation the component is providing. It must be set to "Breadcrumb" like this:

```jsx
<nav aria-label="Breadcrumb">...</nav>
```

You can read more about the `aria-label` property [here](https://www.w3.org/TR/wai-aria-1.1/#aria-label).

### `aria-current`

This attribute is applied to the last link in the list so it will be presented as the current page's link. We can accompomplish this by using the second parameter passed to our callback to [the `map` method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map), which is the index of the current element in the array. If the index we're looking at is one less than the length of the index, then we're looking at the last element in the array and need to apply the `aria-current="page"` attribute to the `<a>` element we're rendering. Otherwise, the attribute should be `undefined`. Let's also add a unique `key` to each `<li>` while we're at it.

Here's what the `<ol>` element should look like now:

```jsx
<ol>
  {links.map((link, index) => {
    const isLastLink = index === links.length - 1;
    return (
      <li key={`breadcrumb-link-${index}`}>
        <a href={link.href} aria-current={isLastLink ? 'page' : undefined}>
          {link.label}
        </a>
      </li>
    );
  })}
</ol>
```

We also probably want to style the current page's link differently to indicate that it's the page we're on. We can do this in our SCSS file by selecting on the `aria-current` attribute. You'll want to add this to the `ol` section of the file:

```scss
[aria-current='page'] {
  font-weight: bold;
  text-decoration: none;
}
```

You can read more about the `aria-current` state [here](https://www.w3.org/TR/wai-aria-1.1/#aria-current).

## 6. Add Keyboard Interaction

We don't have any keyboard interaction to add to this component! We just need to make sure that Tab and Tab+Shift work as expected with `<a>` elements.

## 7. Perform Manual Tests

I use the [ChromeVox Classic Extension](https://chrome.google.com/webstore/detail/chromevox-classic-extensi/kgejglhpjiefppelpmljglcjbhoiplfn?hl=en) to to do screen reader testing. It's easy to turn on only when I want to do tests by going to `chrome://extensions/` in my browser and toggling the extension on and off.

Here's a video of what the component looks and sounds like when you tab through it:

<video controls><source src="https://firebasestorage.googleapis.com/v0/b/ashleemboyer-2018.appspot.com/o/images%2F2020%2F04%2Fbarc%2Fbarc-01-screen-screen-reader.mov?alt=media&token=a7170255-f499-44c8-b7ab-f4a0a44da728" /></video>

## 8. Add Automated Tests

The tests for this component should be very straightforward since there's no interaction or state changes going on. We don't need to test what happens on click and there's no computation or anything of like going on. This component just loads and shows things, that means the only thing we can really test for is that everything shows correctly on load. We'll be using [Jest](https://jestjs.io/docs/en/getting-started.html) and [Enzyme](https://enzymejs.github.io/enzyme/docs/guides/jest.html) for testing.

### Setting up Enzyme

First, we need to [install and configure Enzyme](https://enzymejs.github.io/enzyme/docs/installation/react-16.html). You can skip to the next section if you've already got it working.

1. Run `npm i --save-dev enzyme enzyme-adapter-react-16` in your terminal to install Enzyme with npm

2. Add the following code to the end of the `setupTests.js` file to configure Enyzme:

```js
import { configure } from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';

configure({ adapter: new Adapter() });
```

### Writing the tests

Since the file is short, I'll paste it now and then walk through what's going on.

```js
import React from 'react';
import { shallow } from 'enzyme';

import Breadcrumb from './Breadcrumb';

const testLinks = [
  { label: 'Test Link 1', href: 'test-link-1' },
  { label: 'Test Link 2', href: 'test-link-2' },
];

describe('<Breadcrumb />', () => {
  it('renders successfully with the correct aria attributes', () => {
    const wrapper = shallow(<Breadcrumb links={testLinks} />);

    const nav = wrapper.find('nav');
    expect(nav).toHaveLength(1);
    expect(nav.props()['aria-label']).toBe('Breadcrumb');

    const anchorElements = wrapper.find('a');
    expect(anchorElements).toHaveLength(testLinks.length);

    const firstAnchor = anchorElements.first();
    expect(firstAnchor.text()).toBe(testLinks[0].label);
    expect(firstAnchor.props()['href']).toBe(testLinks[0].href);

    const lastAnchor = anchorElements.last();
    expect(lastAnchor.props()['aria-current']).toBe('page');
  });
});
```

After all the necessary imports, we have a `testLinks` constant that holds the test values we need to perform our tests. It's good practice to store test values rather than hardcoding them inline for the same reason we don't want to do it in other code: it makes it easier to modify the test values. It's not fun trying to update a bunch of strings in a test file with a few hundred lines of code. Variables are so easy to reference in tests!

Then, we have our main [`describe`](https://jestjs.io/docs/en/api#describename-fn) block that groups all of the tests for this component. We have a single `it` block (alias for [`test`](https://jestjs.io/docs/en/api#testname-fn-timeout)) which runs our single test. In our test, we can then call as many [`expect`s](https://jestjs.io/docs/en/expect#expectvalue) as we want. We've got quite a few here, so let's see what each one testing.

1. First, we shallow render the component. This is an Enzyme concept and you can read about it and it's API Reference [at this link](https://enzymejs.github.io/enzyme/docs/api/shallow.html).

2. One of our specifications for the component is that it wraps everything in a `<nav>` element and that the element has `aria-label="Breadcrumb"` on it. We test for that by using [`find`](https://enzymejs.github.io/enzyme/docs/api/ShallowWrapper/find.html). We only want there to be 1 element, so that's what the first expect is accomplishing. Then, we want to check the [`props`](https://enzymejs.github.io/enzyme/docs/api/ShallowWrapper/props.html) on the `nav` and make sure the `aria-label` prop is correctly set to `"Breadcrumb"`.

3. Next, we want to make sure the correct number of anchor elements are being rendered based on the input given to the component through the `links` prop. Similar to the previous step, we `find` all the `<a>` elements and then expect that there are as many found as we have in our `testLinks` array.

4. Now we can look at the first link rendered to make sure it has both a `label` and `href` being rendered correctly. We get the first anchor element using the handy [`first`](https://enzymejs.github.io/enzyme/docs/api/ShallowWrapper/first.html) method. Then we expect it's [`text`](https://enzymejs.github.io/enzyme/docs/api/ShallowWrapper/text.html) to match the first test link's `label`. Finally, we check the `props` on the element and make sure `href` is set to the test link's `href`.

Note: we only need to perform these expects on the first element because if the first element is rendered correctly, then all the others are too.

5. Last but not least, we need to make sure the last anchor element has the `aria-current` attribute set to `"page"`. And you guessed it! Enzyme also has a [`last`]() method to go with `first`. Similar to how we checked the `aria-label` prop in 2, we expect it to have the string value of `"page"`.

## 9. Write the Documentation

We're almost done! Let's get the documentation written out and then we can admire our beautiful new component as a whole.

1. Open up the Breadcrumb's `README.md` and add an H1 heading and a description/purpose of the component.

```md
# Breadcrumb

This component displays a list of links to show users where they are within an application.
```

2. Add an H2 heading for Properties. This is where we'll describe the props passed into the component. This should be in a table in your file, but for formatting purposes, I am listing them below as a list.

```md
## Properties

**Links**

- Type: Array
- Required: Yes
- Default value: None
- Description: These are the links to show in the breadcrumb. Each has a `label` and an `href` attribute.
```

3. Add another H2 heading for Accessibility. We'll detail keyboard interaction, WAI-ARIA roles, states, and properties, and additional features, just like the WAI-ARIA site does.

```md
## Accessibility

### Keyboard Interaction

Not applicable.

### WAI-ARIA Roles, States, and Properties

- The links are contained in an ordered list within a `<nav>` element
- The `<nav>` element has the `aria-label` attribute set to `"Breadcrumb"`
- The last link in the list represents the current page, and must have `aria-current` set to `"page"`

### Additional Features

- The separators between each link are added via CSS so they are not presented by a screen reader
```

4. Last but not least, we add an H2 heading for Usage. This is where we'll put some code examples for how to use the component.

```md
## Usage

<Breadcrumb
links={[
{ label: "Link 1", href: "" },
{ label: "Link 2", href: "" },
{ label: "Link 3", href: "" }
]}
/>
```

## Conclusion

And that's it! We have an accessible Breadcrumb component. We still have many more accessible React components to make and it's been so much fun this far. Make sure to [follow my channel](https://twitch.tv/ashleemboyer) so you're notified every time I go live!


The first accessible React component in the live series is a breadcrumb.

Build an Accessible React Component

Build an Accessible Breadcrumb Component -- Part 1 in the Accessible React Component Series


## First of all, Thank you so much! 🎉

The "Build a React & Firebase Blog Site" live stream was fantastic! I now have two posts to add to my ["Build a React & Firebase Blog Site" Series](https://dev.to/ashleemboyer/build-a-react-firebase-blog-site-part-1-4gn0) and am considering packaging the series up in an ebook format! You can watch the video on YouTube!

<iframe title="Build a React & Firebase Blog Site" width="100%" height="400px" src="https://www.youtube.com/embed/UA0-DWfIuts" frameBorder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowFullScreen></iframe>

## What's this about? 🤔

In the meantime, I've been thinking about topics for upcoming live coding streams and have decided to make a whole series about building accessible React components. I have GitHub repository with a couple of things in it already, but needed a break from all things outside of work for a while. What better way to pick things back up than with a live series to add to the repository?

## Neat! How's it going to work? ✨

Here's the idea: we'll pick a random widget from the [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices) with an on-screen wheel, then build it in React! If a really complex component is chosen, it might take an extra stream to finish it, but we'll walk through the whole thing from start to finish!

## Let's gooo! 🏃‍♀️

To get notified when I go live on stream, you can [follow me on Twitch](https://twitch.tv/ashleemboyer). If you can't catch the stream live, it'll still be available afterwards to re-watch! I also plan on uploading my videos to YouTube since they don't stay on Twitch forever. I'll also add to the bottom of this post as we make it though the series so everything is nicely grouped together.


This is where you can find all the details for my accessible React component live coding series.

Build an Accessible React Component -- The Live Series


I'll admit: making web apps accessible can be challenging, especially when you're new to it. It requires thinking from the perspective of disabled users and having some knowledge about the assistive tools they use, such as screen readers. You may also feel overwhelmed when you start reading documentation. There is a ton of information out there! So I'm going to share with you my favorite resource that I use when making accessible custom components and I'll also tell you about how I like to use it.

# W3C's WAI-ARIA Authoring Practices

If you don't already know, W3C (The World Wide Web Consortium) is "an international community that develops open standards to ensure the long-term growth of the Web." They have an initiative called The Web Accessibility Initiative (WAI), which provides "strategies, standards, and resources" for making the web more accessible to disabled people. There is a wealth of information here and it's easy to get overwhelmed by it. That's why I recommend starting with the [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/) when you're ready to start looking at some technical documentation on accessibility.

![Screenshot of the WAI-ARIA Authoring Practices webpage.](https://dev-to-uploads.s3.amazonaws.com/i/n12gavis3ns73vbhfx7i.png)

## What you'll find

There are 9 sections. I use the third section the most.

- **Introduction:** Talks about the purpose of the document and what will be discussed throughout.

- **Read Me First:** Covers a couple of ARIA principles, the importance of testing assistive technologies, and warns that the document doesn't cover mobile and touch support.

- **Design Patterns and Widgets:** Shows how to make accessible "widgets" (or components) using WAI-ARIA roles, states, and properties and has requirements for implementing keyboard support. There are 27 examples!

- **Landmark Regions:** Introduces HTML sectioning elements and ARIA landmark roles and explains how they help assistive technology users understand how a web page is laid out.

- **Providing Accessible Names and Descriptions:** Talks about the purpose of accessible names and descriptions, when to use them, how browsers assemble them, and rules for making them.

- **Developing a Keyboard Interface:** Covers the principles of coding keyboard support and why it's important.

- **Grid and Table Properties:** Talks about the ARIA properties that help make grids and tables accessible and how to use them.

- **Intentionally Hiding Semantics with the `presentation` Role:** Discusses what the `presentation` role does and when it's commonly used.

- **Roles That Automatically Hide Semantics by Making Their Descendants Presentational:** Lists the roles/elements that make all of their children have the previously discussed `presentation` role.

## How I use it

Section 3, "Design Patterns and Widgets", is my favorite and the one I read the most. There are so many widgets discussed! Let's look at [the Button subsection](https://www.w3.org/TR/wai-aria-practices/#button) as an example.

Each section starts by explaining what the widget does and what it's used for. If there are multiple types of the widget, it'll briefly cover those too. There are 2 additional types of buttons supported by WAI-ARIA: toggle and menu. I use this section to fully understand the functionality of a widget and also to learn any new terminology I should be using when documenting my own components.

![Screenshot of the first section of the Button widget.](https://dev-to-uploads.s3.amazonaws.com/i/3rhs8nantuv03eua50ia.png)

Sometimes there will be NOTE sections that discuss caveats or additional resources. The one for this widget discusses cases when links need to look like buttons or when buttons need to function like links.

![Screenshot of the note for the Button widget.](https://dev-to-uploads.s3.amazonaws.com/i/zlp5ppilfkehbqpliufj.png)

Next up, there will be a list of links to examples. [The Button widget examples](https://www.w3.org/TR/wai-aria-practices/examples/button/button.html) show how to correctly make a `div` element a button and a toggle button created with an `a` element. I like to read the code examples then use them as a reference when I make a rough initial version of the component in a code sandbox. Making an isolated practice copy prevents any unexpected behavior caused by my codebase and I can do manual testing with assistive technologies with ease.

![Screenshot of the examples section for the Button widget.](https://dev-to-uploads.s3.amazonaws.com/i/tynhp8eh33i2laie7rmb.png)

After that, there's a section about keyboard interaction. For the Button widget, it explains that `Space` and `Enter` activate the button and then goes into deep detail about what happens to focus based on the action performed by the button. The format of this section usually makes it very straightforward to come up with a todo list of what I need to code to make a component accessible to keyboard interaction.

![Screenshot of the keyboard interaction section for the Button widget.](https://dev-to-uploads.s3.amazonaws.com/i/r39znxw9eupjd1apt3nd.png)

Finally, you'll come across a section about the WAI-ARIA roles, states, and properties associated with the component. Like the previous section, it's formatted in such a way that lets me test the effects of each role, state, or property one-by-one in my isolated code sandbox. There are also links to the main documentation for each which I use to better understand their purpose.

![Screenshot of the WAI-ARIA roles, states, and properties section for the Button widget.](https://dev-to-uploads.s3.amazonaws.com/i/x5ntbkr93815gs4y3m3p.png)

## Good luck, and have fun!

When I am approaching something new and potentially daunting, I always try to keep the mentality that the experience will be a fun challenge. It's totally okay if you don't get it right on your first try! That's how coding works in general. It takes practice and patience.

If you ever want to chat with me about accessibility, send me a DM or tweet on Twitter! I love a good accessibility conversation. :)


Want to make your components accessible but not sure about the technical feasibility or how to get started? Take a look at the WAI-ARIA Authoring Practices by W3C!

My Favorite Resource for Making Accessible Custom Components


Next time you walk around some city streets, take a look around.

What's the sidewalk like? If it's made out of bricks, does it look very smooth or are probably half of them loose and uneven? When you come to an intersection, does the ramp to the crosswalk smoothly meet the street? And how about the street between sidewalks? Are there potholes or is the road nicely paved?

If there are stores and restaurants, are they at the ground level or is there a step or two or more to get inside? Are there buttons to activate the doors? When you're in the seating area, are there any booths or extra sets of tables that have steps to get to? If the restaurant has a patio, how much space is there outside of the railings surrounding that area? Is it large enough for a wheelchair going in one direction and a person walking in the other?

These are some of the thoughts that have gone through my head over the past few days. It's actually pretty appalling, the quality of some of our sidewalks and crosswalks. These are just the visible issues most people could see if they'd just stop and look.

Can you imagine what accessibility issues exist that aren't as visible?


Why isn't our world more accessible?


Did you know you can add captions to `<video>` elements with a little HTML and a VTT file? I didn't know until today! It's really easy to do (so long as you format your VTT file correctly... shout out to [Conlin Durbin](https://twitter.com/CallMeWuz) for helping me find that error 😄). At a minimum, you need 3 files:

1. Video, probably `.mp4`
2. WebVTT, where the captions are
3. HTML

## Let's get started

### The HTML

```html
<video width="100%" title="Puppy" controls>
  <source src="Puppiness.mp4" type="video/mp4" />
  <track src="transcript.vtt" label="English captions" default />
</video>
```

This is the easiest step. You only need 3 elements. On the `<video>` element, make you sure you include the [`controls`](https://www.w3schools.com/tags/att_video_controls.asp) attribute. This will allow users to toggle captions or switch to a different langue, if applicable.

The `<source>` element should be your video. Specify its `src` and `type` attributes. The `<track>` element is for the `.vtt` file you'll create in the next step. There are multiple attributes to include here.

- `kind` defaults to "subtitles", but if you specify it you must also include the `srclang` attribute.
- `label` is the title of the track and will be displayed in the video controls menu where captions can be toggled.
- `default` is included to set a track as enabled.

### WebVTT

```
WEBVTT

1
00:00:00.000 --> 00:00:01.000
SAND? OM NOM

2
00:00:02.000 --> 00:00:04.000
NO, BLEH

3
00:00:04.000 --> 00:00:08.000
LEASH! OM NOM

4
00:00:08.000 --> 00:00:10.000
GIVE IT

5
00:00:10.000 --> 00:00:14.000
IS MINE
```

The format for this file is very specific. You must include "WEBVTT" at the top of the file, and then there are sections with white space in between which are called "cues". In the example file I've attached above, the first line of each cue is called the identifier. The next line specifies the timing for the cue. Finally, we have the cue payload. This is where you include the content for each caption. You can do _some_ styling here.

### The final product

Here's a GIF preview of the captions I added to a video of a puppy playing on a sandy beach.

![A puppy tries to pick up its leash, bite too much sand and spits it out, then successfully grabs its leash and tugs on it.](https://thepracticaldev.s3.amazonaws.com/i/0c29s1oopy8xoutfow4b.gif)

### More resources

I wasn't able to find a ton of examples out there, but there are plenty of resources that get into the differences between subtitles and captions, styling abilities, and additional ways to accomplish the same thing as above but with different transcript formats or third-party libraries.

- ["How-to: Using captions with HTML's video element"](https://a11yproject.com/posts/using-caption-services-with-html5-video/) (The A11Y Project)
- ["Web Video Text Tracks Format (WebVTT)"](https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API) (MDN)
- ["HTML `<track>` Tag"](https://www.w3schools.com/tags/tag_track.asp) (w3schools)


Adding captions to an HTML video isn't hard at all. You can get a mini project together in just a few minutes.

Get Started with HTML Video Captions


Not that I feel the need to explain myself, but I want to share that I'm hard-of-hearing. It's genetic and just about everyone on my family's maternal side suffers significant hearing loss. I've had hearing aids since I was 10 years old, and as I've grown up, it becomes more and more clear to me how little people understand about the importance of accessibility.

This post is a bit of a rant since all of the below have been said to me personally (all in one conversation, actually 🤦🏼‍♀️). These are all the things I wish I could've said at the time, but you don't always get to speak out when you're like me. It's exhausting, and I'm writing this post as an ask to **please be more aware of the things you say and how you say them**. You might mean well, but your words can still be incredibly hurtful.

## "It's low priority."

That's pretty clear at this point, but why is that? What's your excuse? Is it too hard? Do you not want to spend the time learning about it? Are there not enough of us that exist for you to be concerned about our needs?

## "We need to beat competitors to market."

Based on my experience in this industry, I wonder if _they_ are even concerned about accessibility. Consumers value companies that value them. You should be trying to stand out beyond having a large number of software features.

## "I get it, but..."

No, you obviously don't. If you did, you wouldn't be saying any of these things to my face. You either think you're super woke _or_ you completely forgot that you're talking to a disabled person. I'm kind of afraid of how you talk about disabled people when you're away from us.

## "There's no point if no one is using it."

So, when people start using it, how do you plan on figuring out how many of them need a more accessible tool if we can't actually use it to tell you? We don't have the time for you to play catch up. We'll just go somewhere else.


I'm a disabled woman and have a few thoughts about how able-bodied people speak to people like me about accessibility.

Posts Related to the "a11y" Tag