If you've been working in web accessibility for a while, you know there are many foundational quick-wins that can go a long way. If you're new to web accessibility, hopefully this doesn't come as a surprise! There are definitely challenging aspects to web accessibility, but it's not all that way. And lucky for us, a lot of the quick-wins are also quick and easy to identify with some automated tools! [`pa11y-ci`](https://github.com/pa11y/pa11y-ci) is just one of those tools.

In this post, I'll show you how I set up a [GitHub Action](https://github.com/features/actions) that runs `pa11y-ci` as a pull request check. The check will run against a Vercel deploy preview, and then the results will be shared as a comment on the pull request for easy visibility.

If at any point you find yourself stuck or needing to troubleshoot, check out a GitHub repository I created that represents the end-result of this guide: https://github.com/ashleemboyer/pa11y-ci-test-app.

## Step 1 (optional): Create a Next.js App

If you don't already have a Next.js App to follow along with, I recommend creating one. There are multiple ways of doing this detailed on [the Next.js Getting Started page](https://nextjs.org/docs/getting-started). To keep things simple for this example, I'm using the Automatic Setup approach.

**To create the Next.js app:**

1. Open a terminal
2. Run `npx create-next-app@latest`
3. When prompted, name the app `pa11y-ci-test-app`
4. Change directory into the new folder: `cd pa11y-ci-test-app`
5. Briefly explore the code and learn your way around

Note: I will be using `npm` instead of `yarn` for the rest of this post. If your generated project uses `yarn`, and you would also like to to use `npm` instead:

1. Run `rm yarn.lock` to delete the file
2. Run `npm install` to create a `package-lock.json` file
3. Run `npm run build` so the `package-lock.json` file can be patched if needed
4. Run `npm install` one more time to download any missing dependencies
5. Run `git add .` to stage the changed files for a commit
6. Run `git commit -m "Using npm instead of yarn"` to commit the changes

## Step 2 (optional): Create and Connect a GitHub Repository

If you followed step 1 and created a new Next.js App, you should follow this step as well. You will need a GitHub Repository for your project in order to run the GitHub Action we're creating.

**To create the GitHub Repository:**

1. Go to [github.com/new](https://github.com/new)
2. If needed, log in to your account
3. Under "Owner", select your account
4. Under "Repository name", enter `pa11y-ci-test-app`
5. Select either "Public" or "Private"
6. Click the "Create repository" button
7. Leave this page open in your browser

**To connect the GitHub Repository to your project:**

1. In a terminal, go to your project folder
2. Run `git remote add origin git@github.com:<YOUR-USERNAME>/pa11y-ci-test-app.git` after replacing `<YOUR-USERNAME>` with the GitHub username you used to create the repository. (Read about [Working with Remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) and [Remote Branches](https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches) if you're curious.)
3. Run `git push -u origin main` to push the code to the repository.
4. Verify these steps were successful by refreshing your new repository's page in your browser

## Step 3: Install and Configure `pa11y-ci`

It's always good to test new tools locally (on your machine) before testing them remotely in a place like a pull request. Testing remotely can be tedious and time consuming, and the results of the testing can also be more difficult to locate and read. And if you happen to be like me and have ADHD, all of that is a recipe for multiple distractions!

Before doing anything else, let's create a new git branch. That will be useful later when we need to create a pull request for our GitHub Action.

**To create a new `git` branch:**

1. In a terminal, go to your project folder
2. Run `git checkout -b add-pa11y-ci`

**To install `pa11y-ci`:**

1. In a terminal, go to your project folder
2. Run `npm install --save-dev pa11y-ci`
3. Open the `package.json` file in your project
4. Verify the `pa11y-ci` package is listed under `devDependencies`

**To configure `pa11y-ci` for local testing:**

1. In your project folder, create a file called `.pa11yci`
2. In the new file, paste the following JSON:

```json
{
  "urls": ["http://localhost:3000/"]
}
```

This configuration tells `pa11y-ci` exactly what `urls` in our app it needs to test.

## Step 4: Test `pa11y-ci` locally (on your machine)

Now that we have `pa11y-ci` installed and configured for local testing, we can get to testing!

1. In your project folder, open the `package.json` file
2. Under the `"scripts"` property, add a new entry: `"pa11y-ci": "pa11y-ci"`
3. Open two separate terminals to your project folder
4. In the first terminal, run `npm run dev` to start the app
5. In the second terminal, run `npm run pa11y-ci` to run the new script we added in step 2

After `pa11y-ci` has finished running, this is how the output should read:

```
> pa11y-ci-test-app@0.1.0 pa11y-ci
> pa11y-ci

Running Pa11y on 1 URLs:
 > http://localhost:3000/ - 1 errors

Errors in http://localhost:3000/:

 • The html element should have a lang or xml:lang attribute which describes the language of the document.

   (html)

   <html><head><meta name="viewport" con...</html>

✘ 0/1 URLs passed
```

Hooray! We have an error, but the good news is that means `pa11y-ci` is working! Now we can progress from local testing towards creating our GitHub Action.

## Step 5: Deploy to Vercel

Our current configuration for `pa11y-ci` only works for when we run our app locally with `npm run dev`. For remote testing, we want `pa11y-ci` to test against real builds and public-facing urls. In order to do that, we need to deploy our Next.js app. We'll use Vercel in this example.

**How to deploy to Vercel:**

1. Go to [vercel.com/new](https://vercel.com/new)
2. If needed, log in to your account
3. Under "Import Git Repository", select "Continue with GitHub"
4. Search for your new repo (mine is called `pa11y-ci-test-app`)
5. Click the Import button in-line with the repo name
6. Click the Deploy button (you should not need to change any configuration)

Once the deploy is complete, you can close this window.

## Step 6: Install and Configure `next-sitemap`

There's another way `pa11y-ci` can be used to test against urls, and that is with the `--sitemap` option. This option is nice when you have a `sitemap.xml` file on your site that updates every time a build occurs. It means you don't have to manually update the `.pa11yci` file's list of urls every time a new page is added. The tool we'll use for generating a `sitemap.xml` file is called [`next-sitemap`](https://www.npmjs.com/package/next-sitemap), which is the tool I use on my own website for `pa11y-ci` testing.

**To install `next-sitemap`:**

1. In a terminal, go to your project folder
2. Run `npm install next-sitemap`

**To configure `next-sitemap`:**

1. In your project folder, create a new file called `next-sitemap.config.js`
2. In the new file, paste the following JavaScript:

```javascript
module.exports = {
  siteUrl: process.env.VERCEL_URL
    ? `https://${process.env.VERCEL_URL}`
    : 'http://localhost:3000/',
};
```

This tells `next-sitemap` what the main url of your site is. If you use a different port number than `3000`, make sure to update the code above to match the port number you use.

## Step 7: Test `next-sitemap` locally (on your machine)

To make sure we have everything configured correctly, we're going to test `next-sitemap` locally just like we did with `pa11y-ci`.

1. In your project folder, open the `package.json` file
2. Under the `"scripts"` property, add a new entry: `"postbuild": "next-sitemap"`
3. In a terminal, go to your project folder
4. Run `npm run build`

The new `postbuild` script we added will run automatically after the `build` script has completed. You should see some new `sitemap` files in the `public` directory. We will add those to the `.gitignore` file in the next section.

You should also see something like this output in the terminal after the `build` script output:

```
> pa11y-ci-test-app@0.1.0 postbuild
> next-sitemap

✨ [next-sitemap] Loading next-sitemap config: file:///pa11y-ci-test-app/next-sitemap.config.js
✅ [next-sitemap] Generation completed
┌───────────────┬────────┐
│    (index)    │ Values │
├───────────────┼────────┤
│ indexSitemaps │   1    │
│   sitemaps    │   1    │
└───────────────┴────────┘
-----------------------------------------------------
 SITEMAP INDICES
-----------------------------------------------------

   ○ http://localhost:3000/sitemap.xml


-----------------------------------------------------
 SITEMAPS
-----------------------------------------------------

   ○ http://localhost:3000/sitemap-0.xml
```

## Step 8: Prepare for and Create a New Pull Request

Hopefully you created a new git branch called `add-pa11y-ci` [in Step 3](#step-3-install-and-configure-pa11y-ci), but it's also okay if you didn't! Go ahead and create it now. We'll need a different branch off of the main one in order to create a pull request in our GitHub repository.

**To prepare for the pull request:**

1. Make sure there is a `/public/sitemap*` entry in the `.gitignore` file. We **do not** want to commit these files since they need to be generated by the Vercel build process.
2. Make sure you have all your new `pa11y-ci` and `next-sitemap` work committed. I'm committing everything at once with the message: `"Adding pa11y-ci and next-sitemap"`.
3. Run `git push --set-upstream origin add-pa11y-ci` to push your new branch up to the repository.

**To create the new pull request:**

1. Go to `github.com/<YOUR-USERNAME>/pa11y-ci-test-app/compare` after replacing `<YOUR-USERNAME>` with the GitHub username you used to create the repository
2. Change the `compare` branch to `add-pa11y-ci`
3. The page should update have at least these 5 changed files:
   - `.gitignore`
   - `.pa11yci`
   - `next-sitemap.config.js`
   - `package-lock.json`
   - `package.json`
4. Click the "Create pull request" button
5. You should see 2 text boxes: one for the name of the pull request and one for the description
6. Fill in the title and description however you need
7. Click "Create pull request"

**To verify everything is set up correctly:**

1. Wait for the `vercel` bot to comment on the new pull request
2. In the new comment, open the "Visit Preview" link in a new tab
3. You should see your app built and running
4. Go to the `/sitemap.xml` page in the same app
5. You should see an XML file with contents that look something like this:

```xml
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>YOUR-APP-URL/sitemap-0.xml</loc>
  </sitemap>
</sitemapindex>
```

## Step 9: Create the pa11y-ci GitHub Action

Now that we have a live website to have `pa11y-ci` test against, we can create the GitHub Action that runs `pa11y-ci`.

**To create the GitHub Action:**

1. In your project folder, create a new folder called `.github`
2. In the new `.github` folder, create another folder called `workflows`
3. In the new `workflows` folder, create a new file called `pa11y-ci.yml`
4. Paste the following content in your new file:

```yml
# Wait to run until after the Vercel deployment has finished
# https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#deployment_status
on: deployment_status

jobs:
  pa11y-ci:
    # Only run if the Vercel deployment was successful
    # https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment_status
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest

    steps:
      # Checkout latest commit of repo
      # https://github.com/actions/checkout#checkout-v3
      - uses: actions/checkout@v3

      # Install project dependencies
      - run: npm install

      # Run pa11y-ci against the generated sitemap
      # https://github.com/pa11y/pa11y-ci#sitemaps
      - run: npm run pa11y-ci -- --sitemap ${{ github.event.deployment_status.target_url }}/sitemap.xml
```

Before committing and pushing this new file, make sure to delete the `.pa11yci` file. It's no longer needed.

**To verify the GitHub Action works:**

1. Commit and push the new `.github/workflows/pa11y-ci.yml` and the removed `.pa11yci` file
2. Go to your pull request in a browser
3. Towards the bottom of the page, wait until you see the `pa11y-ci` check finish
4. The check should fail
5. Click the "Details" link to inspect the failed check
6. You should see the same error that you saw when testing locally in [Step 4](#step-4-test-pa11y-ci-locally-on-your-machine)

## Step 10 (optional): Update the pa11y-ci GitHub Action to add a comment on pull requests

When I added this `pa11y-ci` GitHub Action to my own site's pull requests, I decided to make it also comment results on the pull request. There are a couple of reasons for this:

- Normally you have to click the "Details" link next to a failed pull request check. This takes you to another page and away from the pull request. For me, that means an opportunity to get easily distracted.
- The formatting of results in pull request checks can sometimes be difficult to read. Putting the results in a pull request comment gives an opportunity to re-format them in a more readable way.

So to update the GitHub Action to comment on pull requests, we'll need to tell the `pa11y-ci` command to output its results in a different way, and then we'll add a step to the GitHub Action that reads the output, formats it, and creates a comment.

1. Update the `pa11y-ci` `run` step in `.github/workflows/pa11y-ci.yml` to be:
   ```yml
   # Run pa11y-ci against the generated sitemap
   # https://github.com/pa11y/pa11y-ci#sitemaps
   - run: npm run pa11y-ci -- --json --sitemap ${{ github.event.deployment_status.target_url }}/sitemap.xml |& tee pa11y-output.txt
   ```
2. Add a new step at the end of the file like this:
   ```yml
   # Comment the formatted pa11y-ci results on the PR
   - uses: actions/github-script@v5
     env:
       BODY_PREFIX: ''
     with:
       script: |
         const script = require('./.github/workflows/scripts/pa11y-ci.js')
         await script({ context, core, github })
   ```
3. Add a new folder inside `.github/workflows` called `scripts`
4. Add a new file to `scripts` called `pa11y-ci.js`
5. In the new file, paste the following JavaScript:

   ````js
   const { promises: fs } = require('fs');

   module.exports = async ({ context, core, github }) => {
     // Find this PR & do nothing if this isn't a PR
     const { data } =
       await github.rest.repos.listPullRequestsAssociatedWithCommit({
         owner: context.repo.owner,
         repo: context.repo.repo,
         commit_sha: context.sha,
       });
     const prNumber = data[0] && data[0].number;
     if (!prNumber) {
       return;
     }

     // Read the pa11y output and build the comment body
     const pa11yOutput = await fs.readFile('./pa11y-output.txt', 'utf8');
     const lines = pa11yOutput.split('\n');
     const asJSON = JSON.parse(lines.find((line) => line.startsWith('{')));
     const { total, errors, results } = asJSON;

     let commentBody = `${process.env.BODY_PREFIX}\n<h2>:microscope: pa11y-ci results</h2>\n\n`;
     commentBody += `- Number of URLs tested: ${total}\n`;

     if (!errors) {
       commentBody += `- No errors were found! :tada:\n`;
     } else {
       commentBody += `- Number of errors found: ${errors}. :sob:\n`;

       let formattedOutput = '';
       Object.keys(results).forEach((urlKey) => {
         const errors = results[urlKey];
         if (errors.length < 1) {
           return;
         }

         formattedOutput += `- [${urlKey}](${urlKey}):\n\n`;
         errors.forEach((error) => {
           formattedOutput += '  ```\n';
           formattedOutput += `  ${error.message}\n\n`;
           formattedOutput += `  ${error.selector}\n\n`;
           formattedOutput += `  ${error.context}\n\n`;
           formattedOutput += `  ${error.code}\n`;
           formattedOutput += '  ```\n\n';
         });
       });

       commentBody += `<details><summary>See results :eyes:</summary>\n\n${formattedOutput}</details>`;
     }

     // Get the comments on this PR
     const { data: comments } = await github.rest.issues.listComments({
       owner: context.repo.owner,
       repo: context.repo.repo,
       issue_number: prNumber,
     });

     // Try to find an existing pa11y results comment
     const previousComment = comments.find((comment) =>
       comment.body.startsWith(process.env.BODY_PREFIX),
     );
     if (previousComment) {
       // Update the previous comment
       await github.rest.issues.updateComment({
         owner: context.repo.owner,
         repo: context.repo.repo,
         comment_id: previousComment.id,
         body: commentBody,
       });
     } else {
       // Create a new comment
       await github.rest.issues.createComment({
         owner: context.repo.owner,
         repo: context.repo.repo,
         issue_number: prNumber,
         body: commentBody,
       });
     }

     if (errors) {
       core.setFailed('Errors were found by pa11y-ci');
     }
   };
   ````

6. Commit and push the changes to `.github/workflows/pa11y-ci.yml` and the new `.github/workflows/scripts/pa11y-ci.js` file.

**To verify that everything is working as expected:**

1. Go to your pull request in your browser
2. Wait for the `pa11y-ci` check to finish
3. The check should fail just like it did before
4. Look for a comment by the `github-actions` bot that says "🔬 pa11y-ci results"
5. The comment should say that 1 error was found
6. Expand the "See results 👀" text
7. There should be one error listed that matches the same error you've been seeing

## Step 11. Celebrate! 🎉

Nicely done! You've added a `pa11y-ci` GitHub Action that runs on pull requests. You should be proud. Give yourself a pat on the back. 😊

Use pa11y-ci to test deploy previews before merging pull requests.

How I Added a pa11y-ci GitHub Action to My Next.js Site


Many sites on the web have the same content at the top of every page. The content is commonly a logo that links to the home page and then several links to the main pages of the site. If you navigate the same site regularly, you probably find these navigation links repetitive because you learn to know what's already there. Even when you follow a link to a site you've never been to before, you probably expect there to be a set of navigation links at the top. If you're just trying to read the content of the page and don't care about the header, you'll find Skip Navigation links useful.

## What are Skip Navigation Links?

Skip Navigation Link are pretty straightforward. They enable people to skip the navigation at the beginning of a site and get to the main content of the page. This is really helpful for people who navigate sites without a pointer device, such as a keyboard. Without a Skip Navigation Link, a keyboard user would have to tab through every link, button, etc. that appears before the main page content. While tabbing might not be a difficult task for you personally, it is often more difficult for disabled users, so it's necessary to prevent that difficulty.

## Are there any guidelines for Skip Navigation Links?

Skip Navigation Links fall under [Web Content Accessibility Guideline 2.4: Provide ways to help users navigate, find content and determine where they are](https://www.w3.org/WAI/GL/WCAG20/WD-UNDERSTANDING-WCAG20-20081105/navigation-mechanisms.html). The first Success Criterion for this guideline is called [Success Criterion 2.4.1: Bypass Blocks](https://www.w3.org/WAI/GL/WCAG20/WD-UNDERSTANDING-WCAG20-20081105/navigation-mechanisms-skip.html), and within that is [Technique G1: Adding a link at the top of each page that goes directly to the main content area](https://www.w3.org/WAI/GL/WCAG20/WD-WCAG20-TECHS-20081105/G1). The writeup for Technique G1 lists the following as [requirements for Skip Navigation Links](https://www.w3.org/WAI/GL/WCAG20/WD-WCAG20-TECHS-20081105/G1#G1-procedure) that go to the main content of a page:

1. Check that a link is the first focusable control on the Web page.
2. Check that the description of the link communicates that it links to the main content.
3. Check that the link is either always visible or visible when it has keyboard focus.
4. Check that activating the link moves the focus to the main content.
5. Check that after activating the link, the keyboard focus has moved to the main content.

## What does the code look like?

I just used a little CSS and JSX for my Skip Navigation Link, and I opted for making it visible only when it gets keyboard focus. On my site, I use [Next.js Per-Page Layouts](https://nextjs.org/docs/basic-features/layouts#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. The code looks something like this:

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

const BaseLayout = ({ children }) => {
  return (
    <div className={styles.baseLayoutContainer}>
      <a className={styles.skipNavigationLink} href="#main-content">
        Skip Navigation
      </a>
      <SiteHeader />
      <main id="main-content" className={styles.mainElement} tabIndex={-1}>
        {children}
      </main>
      <SiteFooter />
    </div>
  );
};
```

What's important to note from this code:

1. The Skip Navigation Link is before the `SiteHeader` component that I built for rendering navigation links on my site. Remember: the link must be the first focusable control on the page.
2. The Skip Navigation Link's `href` property references the `id` of the `main` element where I render the content of a page.
3. The `main` element that I'm linking to with the Skip Navigation Link has `tabIndex` set to `-1`. This makes the element focusable but does not include it in the page's tab order. Further reading from TPGi: [Using the tabindex attribute](https://www.tpgi.com/using-the-tabindex-attribute/).

After I figured out the markup, I applied CSS to hide the Skip Navigation Link when not focused and also some CSS to remove the focus outline from the `main` element. The code looks something like this:

```css
.baseLayoutContainer {
  position: relative;
}

.skipNavigationLink {
  left: -10000px;
  position: absolute;
  z-index: 1;

  &:focus {
    left: 0;
  }
}

.mainElement:focus {
  outline: none;
}
```

What's important to note from this code:

1. The parent container of the Skip Navigation Link, specified by the `baseLayoutContainer` class name, has `position: relative` set. This is important because `position: absolute` is set on the Skip Navigation Link.
2. The Skip Navigation Link has `position: absolute`, `left: -10000px`, and `z-index: 1` set. This set of properties places the link off the left side of the page by 10,000 pixels and ensures it's placed on top of other elements using `z-index`. You may have to tweak this value if you have used it in other places in your app.
3. When the Skip Navigation Link is focused, the `left` position is updated to `24px`, moving it to be in view in the page.
4. When the `main` element (specified by the `mainElement` class name) is focused, `outline` is set to `none` so that no focus outline shows on the element after navigating to it with the Skip Navigation Link.

## Conclusion and Further Reading

And that's all! Skip Navigation Links are a super quick accessibility win with a ton of value since they help so many folks. Celebrate your quick win and keep the momentum going! [Consider adding a scroll-to-top link next if you haven't already](/blog/accessible-smooth-scroll-to-top-buttons-with-little-code).

### Further reading

- [Add a "Skip Navigation" Link to Help Keyboard Users Reach Main Content Faster](https://dequeuniversity.com/tips/add-skip-navigation-link)
- [Technique G123: Adding a link at the beginning of a block of repeated content to go to the end of the block](https://www.w3.org/WAI/GL/WCAG20/WD-WCAG20-TECHS-20081105/G123.html)
- [Technique G124: Adding links at the top of the page to each area of the content](https://www.w3.org/WAI/GL/WCAG20/WD-WCAG20-TECHS-20081105/G124.html)


Adding a "Skip Navigation" link is as easy as adding a few lines of code.

How I Added a Skip Navigation Link to My Next.js Site


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!

## The What

"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.

## The How

So how to 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.

## The Why

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 use it?

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](/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](/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](https://nextjs.org/docs/basic-features/layouts#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.

You can read and practice with HTML semantic elements [here](https://www.w3schools.com/html/html5_semantic_elements.asp), on W3Schools.


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&mdash;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&mdash;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

She's written 11 posts