Accessibility

Web accessibility (also known as a11y) refers to the practice of creating websites that can be used by anyone — be that a person with a disability, a slow connection, outdated or broken hardware or simply someone in an unfavorable environment. For example, adding subtitles to a video would help both your deaf and hard-of-hearing users and your users who are in a loud environment and can't hear their phone. Similarly, making sure your text isn't too low contrast will help both your low-vision users and your users who are trying to use their phone in bright sunlight.

Ready to start but aren’t sure where?

Checkout the Planning and managing web accessibility guide provided by World Wide Web Consortium (W3C)

You should add a link at the top of each page that goes directly to the main content area so users can skip content that is repeated on multiple Web pages.

Typically this is done on the top of App.vue as it will be the first focusable element on all your pages:

<span ref="backToTop" tabindex="-1" />
<ul class="skip-links">
  <li>
    <a href="#main" ref="skipLink" class="skip-link">Skip to main content</a>
  </li>
</ul>

To hide the link unless it is focused, you can add the following style:

.skip-links {
  list-style: none;
}
.skip-link {
  white-space: nowrap;
  margin: 1em auto;
  top: 0;
  position: fixed;
  left: 50%;
  margin-left: -72px;
  opacity: 0;
}
.skip-link:focus {
  opacity: 1;
  background-color: white;
  padding: 0.5em;
  border: 1px solid black;
}

Once a user changes route, bring focus back to the very beginning of the page, right before the skip link. This can be achieved by calling focus on the backToTop template ref (assuming usage of vue-router):

<script>
export default {
  watch: {
    $route() {
      this.$refs.backToTop.focus()
    }
  }
}
</script>
<script setup>
import { ref, watch } from 'vue'
import { useRoute } from 'vue-router'

const route = useRoute()
const backToTop = ref()

watch(
  () => route.path,
  () => {
    backToTop.value.focus()
  }
)
</script>

Read documentation on skip link to main content

Content Structure

One of the most important pieces of accessibility is making sure that design can support accessible implementation. Design should consider not only color contrast, font selection, text sizing, and language, but also how the content is structured in the application.

Headings

Users can navigate an application through headings. Having descriptive headings for every section of your application makes it easier for users to predict the content of each section. When it comes to headings, there are a couple of recommended accessibility practices:

  • Nest headings in their ranking order: <h1> - <h6>
  • Don’t skip headings within a section
  • Use actual heading tags instead of styling text to give the visual appearance of headings

Read more about headings

<main role="main" aria-labelledby="main-title">
  <h1 id="main-title">Main title</h1>
  <section aria-labelledby="section-title-1">
    <h2 id="section-title-1"> Section Title </h2>
    <h3>Section Subtitle</h3>
    <!-- Content -->
  </section>
  <section aria-labelledby="section-title-2">
    <h2 id="section-title-2"> Section Title </h2>
    <h3>Section Subtitle</h3>
    <!-- Content -->
    <h3>Section Subtitle</h3>
    <!-- Content -->
  </section>
</main>

Landmarks

Landmarks provide programmatic access to sections within an application. Users who rely on assistive technology can navigate to each section of the application and skip over content. You can use ARIA roles to help you achieve this.

HTML ARIA Role Landmark Purpose
header role="banner" Prime heading: title of the page
nav role="navigation" Collection of links suitable for use when navigating the document or related documents
main role="main" The main or central content of the document.
footer role="contentinfo" Information about the parent document: footnotes/copyrights/links to privacy statement
aside role="complementary" Supports the main content, yet is separated and meaningful on its own content
search role="search" This section contains the search functionality for the application
form role="form" Collection of form-associated elements
section role="region" Content that is relevant and that users will likely want to navigate to. Label must be provided for this element

Read more about landmarks

Semantic Forms

When creating a form, you can use the following elements: <form>, <label>, <input>, <textarea>, and <button>

Labels are typically placed on top or to the left of the form fields:

<form action="/dataCollectionLocation" method="post" autocomplete="on">
  <div v-for="item in formItems" :key="item.id" class="form-item">
    <label :for="item.id">{{ item.label }}: </label>
    <input
      :type="item.type"
      :id="item.id"
      :name="item.id"
      v-model="item.value"
    />
  </div>
  <button type="submit">Submit</button>
</form>

Notice how you can include autocomplete='on' on the form element and it will apply to all inputs in your form. You can also set different values for autocomplete attribute for each input.

Labels

Provide labels to describe the purpose of all form control; linking for and id:

<label for="name">Name: </label>
<input type="text" name="name" id="name" v-model="name" />

If you inspect this element in your Chrome DevTools and open the Accessibility tab inside the Elements tab, you will see how the input gets its name from the label:

Chrome Developer Tools showing input accessible name from label

[!WARNING] Warning: Though you might have seen labels wrapping the input fields like this:

<label>
  Name:
  <input type="text" name="name" id="name" v-model="name" />
</label>

Explicitly setting the labels with a matching id is better supported by assistive technology.

aria-label

You can also give the input an accessible name with aria-label.

<label for="name">Name: </label>
<input
  type="text"
  name="name"
  id="name"
  v-model="name"
  :aria-label="nameLabel"
/>

Feel free to inspect this element in Chrome DevTools to see how the accessible name has changed:

Chrome Developer Tools showing input accessible name from aria-label

aria-labelledby

Using aria-labelledby is similar to aria-label except it is used if the label text is visible on screen. It is paired to other elements by their id and you can link multiple ids:

<form
  class="demo"
  action="/dataCollectionLocation"
  method="post"
  autocomplete="on"
>
  <h1 id="billing">Billing</h1>
  <div class="form-item">
    <label for="name">Name: </label>
    <input
      type="text"
      name="name"
      id="name"
      v-model="name"
      aria-labelledby="billing name"
    />
  </div>
  <button type="submit">Submit</button>
</form>

Chrome Developer Tools showing input accessible name from aria-labelledby

When this pattern is used inside a reusable component, generate the IDs with useId() instead of hard-coding them. This keeps each component instance's id values unique while still linking the visible text to the form control:

<script setup>
import { useId } from 'vue'

const sectionId = useId()
const nameId = useId()
</script>

<template>
  <section class="form-section">
    <h2 :id="sectionId">Billing</h2>

<label :id="nameId" :for="`${nameId}-input`">Name: </label>
    <input
      :id="`${nameId}-input`"
      type="text"
      name="name"
      :aria-labelledby="`${sectionId} ${nameId}`"
    />
  </section>
</template>

aria-describedby

aria-describedby is used the same way as aria-labelledby except provides a description with additional information that the user might need. This can be used to describe the criteria for any input:

<form
  class="demo"
  action="/dataCollectionLocation"
  method="post"
  autocomplete="on"
>
  <h1 id="billing">Billing</h1>
  <div class="form-item">
    <label for="name">Full Name: </label>
    <input
      type="text"
      name="name"
      id="name"
      v-model="name"
      aria-labelledby="billing name"
      aria-describedby="nameDescription"
    />
    <p id="nameDescription">Please provide first and last name.</p>
  </div>
  <button type="submit">Submit</button>
</form>

You can see the description by inspecting Chrome DevTools:

Chrome Developer Tools showing input accessible name from aria-labelledby and description with aria-describedby

Placeholder

Avoid using placeholders as they can confuse many users.

One of the issues with placeholders is that they don't meet the color contrast criteria by default; fixing the color contrast makes the placeholder look like pre-populated data in the input fields. Looking at the following example, you can see that the Last Name placeholder which meets the color contrast criteria looks like pre-populated data: