Dev Docs

# Accessibility

Most websites we create at Sideways are bound to comply to the Americans with Disabilities Act (opens new window). Because of this, we often have to ensure our websites are as accessible as possible, otherwise there could be important legal consequences for our clients. For most of our clients, making a site ADA compliant requires being compliant with WCAG 2.1 Level AA (opens new window).

More importantly, we as developers have a moral obligation to create accessible websites for everybody. This not only means complying with WCAG 2.1 but also having the user in mind in any UX/UI features we deploy, from the design to the implementation phase.

Useful resources to learn more:

# Assessments

An assessment is the process of validating a given website, component or page is compliant to some set of rules, such as WCAG 2.1 Success Criteria. There is no way to do an automatic assessment for full WCAG compliance. There are tools that can help uncover problems, but in order to get an accurate picture of how the websites works for users with disabilities manual testing is necessary.

Automatic tools can detect around 30% of the total possible issues a site can have, this is still valuable as a first pass before running a manual scan.

TIP

Doing manual assessments requires some accessibility training. Be sure to at least get familiar with accessibility basics before attempting a manual scan.

Here are the tools we use:

# Performing an accessibility assessment

# Automatic and Guided Assessments

  1. Decide on what you are testing:
    • If testing a single module or component: create an empty page with just instances of that module/component. Ensure you add as many variants as possible of it (e.g. render all possible states of a module given different ACF settings)
    • If testing a full site: pick a representative sample of pages based on revenue value, such as the homepage, pages containing booking widgets, sales forms and interactive features, 4-9 pages should be enough most of the time.
  2. Run a Guided Accessibility Assessment from the Accessibility Insights Chrome extension. See the Accessibility Insights instructions (opens new window).
  3. Run the "Automated Checks" portion of the assessment
  4. Follow the instruction of the remaining sections of the guided assessment, recording failures as you go.
  5. Now you will check critical parts of the website using Screen Readers. Follow the sections below and ensure you are using only a keyboard (and not your mouse). Record all failures describing where the error is, what Screen Reader and browser you were using and how to reproduce it. If possible, record issues on the same "Accessibility Insights" instance by finding the correct section and recording a failure.
    • If you are on Mac, use VoiceOver on Safari. If on Windows, use NVDA on Firefox.
    • For mobile, use VoiceOver on Safari Mobile and TalkBack on Chrome for Android.
  6. Once done, export a report of the guided assessment. If you recorded issues outside the assessment tool you must manually add them to the comment section (using markdown).

# Forms

Check labels and instructions:

  • Field labels are exposed to assistive technologies. Place the focus on the form input (text field, radio button, etc.). The label associated with the form input should be rendered by the screen reader. If not, the label is not marked up properly.
  • Instructions are available to assistive technology users. Use a screen reader and place focus on the form element. The screen reader should render instructions to users when focus is placed on the form element.

Check validation:

  1. Locate a form on the web page.
  2. Do not fully complete the form, especially fields that are required or require special formatting (make mistakes on purpose).
  3. Submit the form.
  4. Check that feedback is rendered by the screen reader immediately after submission.
    • A global error summary may be provided
      • Note: It is a best practice to ensure a method is provided to quickly access errors in the form in the error summary (e.g., a link to go to the first error in the form)
    • Or focus may be shifted to first form element with an error
  5. Navigate to all the form elements with specific errors and make sure the error messages for those particular form elements are conveyed through the screen reader.

Do the same for success messages, completing the form correctly this time.

  1. Check that a success message is provided immediately after submission. The success message should be visible and have meaning (e.g., "Your form has been successfully submitted.").

# Custom Widgets

  1. Interact with each user interface components such as booking widgets, sliders, tabs, maps, accordions and any interactive component.
  2. Check that the information conveyed through the screen reader accurately conveys what is displayed as you interact with the components.
  3. Make sure that the information is reliable and that the components are compatible with the screen reader.

Each type of custom widget has its own set of requirements, so it's difficult to write a generic guide to test them. What you need to keep in mind is that custom widgets should be as simple to use as possible using only the keyboard and the hearing aids from the screen reader, if you need to depend on reading something on the screen by yourself to finish a task, that's a problem.

Try to complete all the important flows in the widget context, for example:

  1. In a booking widget, try to actually set up a reservation
  2. In a complex gallery or slideshow, try to navigate between slides/images and "see" (hear) the content
  3. In an interactive map with an archive component, ensure that you can access the individual items without having to interact with the map points directly.

# Common accessibility dilemmas

# <button>, <a> or <div>?

TIP

Use anchors when linking to proper URLs (both internal or external) or sections of a page (with #section). Use buttons for everything else.

In very rare cases you may need to use a clickable <div> instead of a button. In those cases you must define the proper aria roles and JS event handlers for it to be accessible. See ARIA: button role (opens new window)

See:

# <img> or <div style="background-image: url(...)"> ?

TIP

Is this graphic part of the content or part of the design? Use <img> for content, background-image otherwise.

Most images that come from a CMS should use <img>, except when they are for decorative purposes, and their absence wouldn't matter otherwise.

Keep in mind that background CSS properties like background-size and background-position can be replaced in <img>s with object-fit or object-position. However, you will need to ensure the appropriate polyfill is in place for IE11.

See:

←