Component library accessibility audit

The first project my manager tasked me with at my new job as a senior accessibility engineer in the Design Engineering organization was to perform an accessibility audit of the component library our team provides to the engineering team who codes the dotcom website. These components are generally page level rather than UI level, think a card or a form. In total, I audited 28 components in the context of the component library, not as the components have been implemented into the dotcom site.

Auditing solo components

Auditing components is necessary—all code should be tested for accessibility standards—but presenting a component alone on an empty page in the context of a component library has limitations.

Placeholder content

I don’t like working with placeholder content. Design should follow content creation so examples should be able to use real text and images. Instructions about how to create content should be presented separately along with instructions for how to markup content, e.g. “Optional Header” is an <h2>.

Announcing Optional Header (60 chars) The main body of the banner should be used to display the content of the banner's messages, supported by the header. (150 char max)
An example banner from the component library

This is the issue I created for this example banner which is HTML text over a background image:

In banner variations with text on a lifestyle background image, when zoomed in up to 400% at a viewport width of 1280px, some text may overlap portions of the image that do not provide enough color contrast.

It’s difficult for me to tell if this is just a bad example image or a true color contrast concern.

No context

This complication popped up on the first component I tested: Alerts. The library page presented these message boxes on a blank page. I wasn’t sure if the message boxes were supposed to be there on page load or if something triggered them. This matters because the message box containers have the role="alert" attribute.

two example alerts with an icon, message text and learn more link
Example alerts from the component library

The alert role is a type of status message. It’s supposed to be assigned to a container that is empty on page load. Then, when something happens on the page, the alert is loaded into the empty container and immediately announced to assistive technology because of the alert role. It’s not designed to include a call to action like “learn more” links.

I looked at the dotcom production site and saw an alert displayed on page load. Because it has the alert role, assistive technology announces the content of this message box before anything else, before even the name of the webpage or website. It also announces the message box content twice because it is the first thing on the page.

I decided someone got carried away with the ARIA and advised that they remove the role="alert" attribute because these message boxes do not fit the expected design pattern for an alert.

Not our problem

In The Book on Accessibility chapter “Accessibility Coaching Guide”, the section “Not our problem” covers one of the pitfalls of depending solely on component library accessibility: The component library is accessible, so the development team doesn’t think it has to worry about anything.

While an individual component can be completely accessible, they can be used in patterns that are completely inaccessible.

A helpful analogy is building a wall with bricks. Individually bricks are quite strong, but they can be arranged in a way that is fragile and very weak.

This is ultimately why I was tasked with this audit. Our team wants to ensure we are not introducing any accessibility issues in the code we provide. Then we can trace any accessibility issues in production to either the dotcom engineering team’s implementation of these components or to the content entry team.

Example component audit results

The format I used in my report was to provide a bulleted list of accessibility issues I found. I did not note the specific WCAG success criteria affected because I didn’t think the team needed to know that information.

Below the bulleted list of issues, I have a “Recommendations” heading where I repeated the same bulleted list but with the advice for how to remedy each issue. Below that is an optional section for “Resources” where I link to different articles or documentation to support the remediation advice.


The carousel does not follow the expected design pattern.

A carousel with a banner image and text. Controls include a play/pause button, tabs for each slides and previous/next buttons.
An example carousel from the component library
  1. The carousel is missing the expected role and accessible name.
  2. Slides and slide picker controls are missing the expected role and accessible name.
  3. Carousel controls are located after the slide content.
  4. The “play/pause” control has a confusing accessible name.
  5. The slide picker controls do not have sufficient contrast with the page background.
    • Foreground: #999898
    • Background: #FFFFFF
    • Contrast ratio: 2.88:1
  6. “Previous” and “next” controls do not have appropriate accessible names.
  7. The carousel does not stop advancing when a keyboard user activates the “previous” or “next” controls.
  8. Visible text beneath the slide heading is hidden from assistive technology.
  9. The “Call to action” control is a <button> element inside a link.
  10. Decorative slide images are announced by assistive technology.
  11. Hidden slide content is accessible to assistive technology.


  1. Add the aria-roledescription="carousel" attribute to the <section> element used to markup the carousel container. Provide an accessible name with the aria-label attribute.
  2. Markup slides and slide picker controls with tabpanel and tab roles with accessible names. See example. This includes enabling arrow keys to switch between slide tabs.
  3. Ensure carousel controls get keyboard focus before slide content. Group the “play/pause”, “previous” and “next” controls.
  4. When changing the name of a control depending on its state, do not use a toggle control. Remove the aria-pressed attribute from the “play/pause” control.
  5. Ensure slide picker controls have at least 3:1 contrast with the background.
  6. Remove the title and role attributes from the button <svg> elements for the “previous” and “next” controls; add the aria-hidden="true" attribute to hide them from assistive technology. Use the aria-label attribute on the button to provide the control with an accessible name.
  7. The carousel should stop advancing when any part of it has keyboard or mouse focus.
  8. Remove the aria-hidden="true" attribute from the visible slide text so that it is conveyed by assistive technology.
  9. Use either a link or a button for the “call to action” but not both.
  10. Ensure decorative slide images are hidden from assistive technology by providing an empty alt attribute.
  11. When a slide is visually hidden, it should also be hidden from assistive technology. This can be achieved by using the display:none CSS property on hidden slides or by adding the aria-hidden="true" attribute.


Common issues

Overall, the issues I found were pretty typical. It’s obvious people working on this component library have some accessibility knowledge and tried to create an accessible experience but likely did not do adequate testing with assistive technology, like a screen reader.

  1. Multiple ARIA issues with controls missing the expected roles and accessible names
  2. Decorative images and icons not hidden from assistive technology
  3. Information not available in smaller viewports or when zoomed to 400% at 1280px wide
  4. Color contrast issues with both text (4.5:1) and control borders (3:1)
  5. Some controls are not keyboard accessible


Testing a component library is challenging when it presents placeholder content without surrounding content for context. Testing the structure of a component is good for catching ARIA and resize issues but has limited value in ensuring the resulting website is accessible. Remember to test a representative sample of pages from your website that uses each of the library components with real content. What matters is how accessible your final content is.

5 neurodivergent UX fails while buying Alamo Drafthouse tickets online

I went to the movies this week for the first time since the pandemic began. I looked up showings at the Alamo Drafthouse and discovered little has improved with their payment process since I reviewed it on desktop back in 2016. This time, I completed the purchase on an iPhone using the responsive mobile website in the Firefox browser.

While I found several accessibility issues with the site, I’m highlighting concerns with the “Payment” screen. I’m neurodivergent and this post focuses on five things that cause me anxiety and make the experience frustrating:

  1. Required fields are not marked
  2. Submit button is disabled
  3. Error messages don’t offer suggestions
  4. Data formats are placeholder text
  5. Optional checkbox is already checked

Required fields are not marked

I’ve done enough online ordering that I assumed that all the credit card-related fields are required, but many people will not understand that. E-commerce research suggests that marking all fields, required or optional, improves the customer experience. It certainly lessens my anxiety to know exactly which fields to complete.

screenshot of the payment screen with form fields with placeholder text for Card Number, Cardholder Name, EXP, CVV and Zip code. The "Buy Tickets" button is disabled.

Not only are required fields not clearly marked, but merely interacting with a field causes the display of an angry, red “Required” message. (This does not work for the “EXP” field even though it is required.) These input fields use a combination of the HTML required attribute with an aria-describedby attribute for the error message which causes assistive technology to announce fields are required multiple times.

screenshot of the payment screen with red error messages denoting several fields are required

Submit button is disabled

From the previous screenshots, we can see the next issue that causes me a lot of anxiety when using a website. The “Buy Tickets” button, which is the submit button for the form, is disabled by default. The button becomes enabled only after data has been entered into all the required form fields, which are not clearly marked.

There are two more required form fields below the credit card fields but they are easy to miss because of the sticky footer with the “Buy Tickets” button, meaning that after entering all credit card details, this button is still disabled.

Error messages don’t offer suggestions

The default error message for empty fields is “Required”. If a user enters data in the wrong format, the error messages change to “Invalid”. This doesn’t help the user in any way to figure out how to fix the error.

screenshot of the payment screen with bad data entered into several fields which each have an error message of invalid.

Here are some examples of helpful error messages:

  • Card Number: Please enter 16 digits
  • EXP: Please enter 2-digit year
  • CVV: Please enter 3 digits
  • Zip Code: Please enter 5-digit US zip code

“Zip Code” is the only field requesting numerical data that displays the numerical keyboard on mobile devices. Adding the inputmode="numeric" attribute to every field requesting numerical data will display the numerical keyboard too, which improves the accuracy of data entered into these fields.

Screenshot of the payment screen with focus in the Zip Code field which displays the 10-key numerical keyboard on mobile devices

Data formats are placeholder text

The requested data format for all the “Payment” screen fields are implemented as placeholder text. This means that once a person starts to enter data into the field, the required formatting of that data disappears. People are forced to recall from memory how to enter the data correctly. On top of this, the “EXP” and “CVV” fields allow someone to enter more digits than the data format allows.

The video below demonstrates what a person using assistive technology, like a screen reader, experiences when exploring the form. Notice how placeholder data are not consistently announced by VoiceOver.

Optional checkbox is already checked

Following the credit card-related fields is the “Email Confirmation” section which includes a checkbox that is already checked:

Join Alamo Victory

By checking “Join Alamo Victory” you start earning visits with this purchase for rewards and you agree to Alamo Drafthouse Cinema’s terms of use.

Email confirmation section with email address and confirm email address fields followed by a checkbox that is already checked for Join Alamo Victory

This is an optional field. It should require that I choose to check it. Because of its location behind the sticky footer, it’s very likely people will not see this checkbox and inadvertently join this program. Having to look for sneaky UI patterns like this makes for a bad experience.


This website has made some improvements like providing a “Back” button after timeout and inline form field validation. I also give the developers kudos for appropriately implementing the autocomplete attribute on the credit card-related fields. I’d make the following changes to the “Payment” screen to create a better experience for neurodivergent people:

  1. Clearly indicate which form fields are required
  2. Don’t disable the submit button
  3. Offer suggestions for fixing data input errors
  4. Display required data formats at all times
  5. Don’t pre-check checkboxes for optional promotions

Preparing for an accessibility test

This is the first article in a series about how to run an accessibility test. The companion video and information on performing an accessibility test are available from the Accessibility Testing project page.

If you’re new to accessibility, check out the many resources at the W3C Web Accessibility Initiative (WAI). A good, free foundational course is the W3C Introduction to Web Accessibility.


When I started learning about testing for web accessibility, I came across a lot of checklists of what to test for but I struggled with two things. One, I didn’t understand the Web Content Accessibility Guidelines (WCAG) well enough to know if I was covering everything. Two, I didn’t know where on the page to start testing and how much I should test at a time.

The answer to both of these is to start somewhere. A little bit of accessibility testing of what you understand is better than no testing. I like to think of accessibility as a spectrum from less accessible to more accessible. Our goal is to improve access to our websites—a progressive and ongoing task. Accessibility is a huge discipline with many facets that takes time to do well. I hope this project helps ease you into the process.


At the beginning of each test, we must establish what we are testing for given the different versions and levels of WCAG. Industry standard is to test WCAG 2.1 Level A and AA, 50 discrete success criteria (SC); that is what this methodology follows. What I found overwhelming was the best order in which to test each SC. Do I start at the top with 1.1.1 Non-text Contrast? What if an SC isn’t applicable to the webpage I’m testing?

I’ve created an accessibility testing spreadsheet to help with this.

Download the accessibility testing spreadsheet (Updated 26 January 2024)

The Overview sheet is a place to list the project name, date, WCAG version being tested, the environment used for testing (browser/screen reader combinations) and any tools used for testing.

The Scope sheet is a place to track what you’ll be testing. Later on in the Scope section, I address how to break up a page into components, or chunks of content, for testing. Provide each component with an ID, name, description of how to locate the component and the URL of test page. Update the “Status” column to reflect if the component is in testing, under review or completed.

Below I outline the columns in the Component sheet. For each component tested, create a clone of the Component sheet and rename it. The workbook includes two components to start.


Each of the 50 SC are assigned a “Type” category. The spreadsheet is sorted by “Type” initially, grouping related SC into the following 12 categories:

  • Active Controls
  • Adaptability
  • Contrast
  • Dynamic Changes
  • Errors
  • Interactivity
  • Keyboard
  • Multimedia
  • Order and Focus
  • Page Level
  • Semantics
  • Sensory

Let’s look at the SC under “Active Controls” to understand how grouping SC makes testing easier:

  • 1.3.5: Identify Input Purpose
  • 2.4.4: Link Purpose (In Context)
  • 2.5.3: Label in Name
  • 3.2.1: On Focus
  • 3.2.2: On Input
  • 3.3.2: Labels or Instructions

We can see from the SC numbers that these are spread across a number of guidelines with gaps in the numerical order. While there’s nothing wrong with starting at 1.1.1, I find it easier to test related SC at the same time.

WCAG success criterion

This spreadsheet lists all 50 SC (rows 2-51). Each success criterion is linked to its W3C “Understanding” page which lists use cases and remediation resources. You can sort the “WCAG Success Criterion” column to reorder the SC from 1.1.1 to 4.1.3 instead of using the “Type” grouping.


Each success criterion displays its WCAG level, A or AA. You can filter the “Level” column to display just A or just AA.

WCAG criterion description

The quick reference description of each success criterion is listed in the “WCAG Criterion Description” column. In part two, I discuss what each success criterion covers from a testing perspective and what to look for. In some cases, I’ve added examples or code snippets for reference. Take some time to read these over and understand what WCAG covers.


The “Status” column has a pick list with three values for tracking your testing progress: N/A, Pass and Fail. I like to go through the 50 SC and mark any that don’t apply to the content I’m testing as “N/A”. For example, if there is no video or audio content on your testing page, you can eliminate six of the “Multimedia” SC from testing right away.

If you do not find any issues for a success criterion, mark it as “Pass”. If you find any issues at all for a success criterion, mark it as “Fail”. Filter the “Status” column to see only “Pass” or “Fail” results.


This is where you will write up any accessibility issues you find while testing the component. Let’s look at an example. You’re testing 2.4.4: Link Purpose (In Context). The test page lists several articles with “Read More” links. You test with a screen reader and they are all announced the same: read more. This means an assistive technology user cannot distinguish one link from the next.

In the “Issues” column, write a concise description explaining

  • What content has the issue (“Read More” links)
  • What the issue is (links don’t provide context)
  • Why it’s an issue (users of assistive technology can’t distinguish between “Read More” links)

For simplicity, I suggest writing up all issues you find with each success criterion in the same “Issues” cell instead of creating a new row for each issue.

Use the browser inspector (F12) to determine if there are issues with the HTML.

The Inspector tab displaying HTML and CSS code in Firefox Devtools
Firefox Devtools – Inspector tab


In addition to identifying issues, we should provide advice on how to remediate the issues. This takes time. It’s only through the experience of testing different kinds of content that you learn the best way to solve accessibility issues. You might want to make recommendations after completing all testing if you need to look up examples and research how to fix problems. Writing solid remediation advice comes with patience and practice.

You need to have a good understanding of how HTML and CSS work to display content. You need to have a basic idea of how JavaScript controls page behavior, for example, enabling a button to open a menu. You don’t necessarily need to be able to code JavaScript but you do need to be able to discuss expected behavior and how to achieve it programmatically, like adding keystroke events for ENTER and SPACE keys to make a custom button keyboard accessible.

Use the browser inspector (F12) to test proposed solutions by modifying the HTML and CSS. I address this further in part two.

Source code

The browser inspector enables you to copy a source code snippet from the HTML or CSS to paste into the “Source Code” column of the spreadsheet. This enables developers to locate the issue more easily in their code base for remediation.

<a href="article.html">Read More</a>


Industry standard is to test with two or more of these combinations:

  • Chrome browser and JAWS screen reader on Windows
  • Firefox browser and NVDA screen reader on Windows (this demonstration)
  • Safari browser and VoiceOver screen reader on Mac

Below are the most-used browser/screen reader combinations in use according to the WebAIM Screen Reader Survey #9 (May-June 2021).

Most common screen reader and browser combinations
Screen Reader & Browser# of Respondents% of Respondents
JAWS with Chrome50032.5%
NVDA with Chrome24616.0%
JAWS with Edge19412.6%
NVDA with Firefox1499.7%
JAWS with Firefox744.8%
VoiceOver with Safari724.7%
NVDA with Edge553.6%
ZoomText/Fusion with Chrome332.1%
JAWS with Internet Explorer301.9%
VoiceOver with Chrome241.6%
ZoomText/Fusion with Edge181.2%
Other combinations1449.4%


I’m using a group of freely available tools for this demonstration but I am not endorsing any one in particular. It’s important to test with different tools to find out what works best for your situation.

A good way to learn about accessibility problems is to use an automated accessibility checker. These tools will scan the source code and outline certain issues that can be tested for automatically, like color contrast. It’s important to double-check these flagged issues for yourself and add issues to the spreadsheet only if the flagged issue is valid.

For this demonstration, I’m using the axe devtools Firefox extension. Once installed, it will add an “axe DevTools” tab to your browser devtools (F12). In part two, we’ll run the scan and explore the results.

Browser devtools panel in Firefox with the axe DevTools tab displayed
axe DevTools tab in Firefox

I use the following tools to help me test for other issues:


It’s important to assess what webpage or website you’re going to be testing so you can break up repeated elements into smaller components. This eliminates the problem of testing the same thing on multiple pages, e.g. navigation. If you’re testing a single webpage, that can often be treated as a single component. But if you’re testing a website with multiple pages, try to save yourself some work by breaking up the content:

  • Header
  • Navigation (global and local)
  • Search
  • Sidebar
  • Footer
  • Main content

Within the main content, you might want to break up lengthy pages into smaller components like carousel, image gallery, form, video player, etc. depending on what content you’re testing. There’s no sense in testing the same kind of content over and over; you want a good sample of the different types of content found within the website. It’s a judgement call by you as the tester as to how large or small a component should be.


You should now have a better idea of what to test and how to test it. In part two, I perform an accessibility test and track my results in the accessibility testing spreadsheet.

View the video: Preparing for an accessibility test

Read part two: Performing an accessibility test