Behind the scenes of creating a new Web Accessibility Annotation Kit
By: Jan Maarten, Daniel Henderson-Ede, and Kevin Oliveira.
The CVS Health® Inclusive Design team has released a new Web Accessibility Annotation Kit on the Figma Community. We want to share how we built these tools and the insights we learned along the way.
Scaling accessibility is a huge challenge for a large enterprise. Many companies start by addressing known issues in their code. As their accessibility practice matures, they may emphasize preventing issues in the design phase, where a significant number of issues originate. This is one of the Inclusive Design team’s missions, supported by two foundational principles in our design organization:
- Everyone should consider accessibility early and often.
- Anyone can do that, whether they specialize in accessibility or not.
In 2021, our team had grown to around four dozen accessibility specialists. We support and advise hundreds of designers, all of us striving for better and more inclusive digital experiences. Once a design is finished, our team would annotate it for accessibility handing it off to developers. These annotations can be a powerful tool to communicate intent and semantics that can’t be conveyed by the visual design alone. They also help our accessibility engineers and QA teams know what to expect when testing.
As our team outgrew old tools and workflows, our design hand-offs grew more difficult.
- Design teams relied on various tools, none of which were well suited to creating or consuming design documentation.
- Our team’s written feedback might be in any of the various tools and in various formats. Finding and following that documentation was a challenge for many, including the developers who we were creating them for.
- While we waited on coded components for our new design system, we relied on a UI library. In practice, this meant that our four dozen accessibility designers might end up annotating the same component in four dozen different ways.
Lacking a single tool to ensure consistency and prevent many avoidable accessibility issues, we couldn’t create a standardized, scalable process.
We decided to leverage Figma, which could allow design specs to be delivered with inline accessibility annotations all at once. We needed a web accessibility annotation kit that was as intuitive and easy for our team to use as it would be for our developers to consume.
The question was whether we could adapt an existing kit or if we would need to create our own.
The challenge
Standardize and streamline our accessibility documentation so developers can build accessible experiences for all.
The team
Three Senior Accessibility Designers within CVS Health® Inclusive Design.
The timeline
- 2 months to initial release
- 18+ months of ongoing support and refinement
Outcomes
- Quickly became one of our top Figma libraries with 150,000+ annotations made across 1,100+ design files. An average of 4,200 stamp inserts made every week, with a record of 7,800.
- Widely adopted and scaled across the enterprise, it was used regularly by 33 agile teams within 5 months, and 65+ teams within 12 months.
- Contributed to a 22% decrease in accessibility issues across the board.
Table of Contents
Research and analysis
At the time, there were a handful of Figma annotation kits from others such as Microsoft, GitLab, Twitter A11y, Indeed, and Intopia. We tested them on some of our designs to see if they could be used as a starting point. As we did so, we saw they presented some significant issues that would hinder us at scale:
- Many had accessibility issues with contrast, legibility, and even meaning. This could affect our colleagues and impact their ability to create and consume annotations.
- Many relied on directional arrows alone to annotate the content or interface. Our more complex designs often needed nested, hierarchical annotations, so this alone isn’t always sufficient.
- Kit components themselves were built in such a way that changing the direction of an arrow would erase any customizations.
- None contained every type of annotation we needed, so we knew we would need to make heavy alterations regardless of which kit we might choose.
Seeing all of this, it was an easy choice to explore creating a new kit that improves upon the others in these key areas.
Accessibility principles
Most design tools have user interfaces with fundamental accessibility issues. Our colleagues who are full-time screen reader users are blocked from creating or perceiving designs with it, let alone annotating them.
Until that is no longer the case, we must make the most of the tools we have by creating with accessibility in mind as much as we are able. For instance, we can still adhere to various WCAG Success Criteria, such as: 1.1.1: Non-text Content, 1.4.3: Contrast, 1.4.1: Use of Color, 1.4.12: Text Spacing, and 2.5.5: Target Size.
Three principles helped ensure our new kit was as accessible as possible:
- Multiple methods to differentiate annotations from designs by using accessible colors, fonts, and visual styles.
- Multiple methods to identify and differentiate annotations by using clear labels, icons, and outlines that help avoid relying on color alone.
- Flexible and robust components built without restrictions on dimensions, fonts, and directional references. Customize it easily and scale it quickly with minimal risk of data loss when using or updating components.
We also needed this kit to be easy to understand — and this applies as much to the pixels we draw as the language we use. Since the word “annotations” could refer to the documentation itself as well as individual components (and is also a mouthful), we have adopted the word “stamp” to refer to the different types of components.
Building the prototype
Types of annotation
We began building annotation stamps based on immediate need and complexity: headings, landmarks, links, buttons, images, focus order, reading order, and a general freeform note. We postponed the addition of complex annotations like form inputs, focus states, and keyboard controls until we had a proof of concept.
Following our accessibility principles to differentiate stamps from designs and one another, each stamp may have its own color, icon, text label, number, outline, shadow, and a directional arrow or outline.
To make a flexible and robust kit, we would need multiple stamp formats.
Formats
- Arrow Stamps point to parts of a design within close proximity, pointing up, down, left, or right.
- Lasso Stamps outline to highlight an area of the design (such as landmarks regions). Labels also need to be able to change placement to reduce risk of overlapping other stamps or important parts of a design.
- Details components are numbered notes in the margins around a design. These could include code semantics, interface behavior, and more. Their numbers always correspond to numbers used by an Arrow or Lasso Stamp.
Light and dark themes
We aimed to exceed the minimum contrast ratio of 4.5:1 with light and dark color themes. Since our brand relied heavily on bold red hues, we sought to avoid this part of the color spectrum, so that any stamps placed would be easy to differentiate from our designs.
The bold white outlines took this one step further and ensured the stamps would pass contrast regardless of a design’s visuals or canvas color. This meant that our light theme could work on any background, so we retired the dark theme to reduce the overall complexity of the kit.
Stress testing for usability
We released our new kit to a half-dozen internal teams and collected data for the next four weeks. Our stress testing included running co-design sessions, training people on how to use the kit, and trying to use the kit to annotate complex design system patterns. This gave us insight into where it fell short, where our assumptions were wrong, and how to improve it.
Outline styles added more confusion than clarity
We thought distinct outline styles for each stamp type would help differentiate one type from another and help not have to rely on color alone. In practice, there was no real benefit. When complex components required multiple outlines inside or adjacent to one another, this became visually overwhelming, and it was harder to differentiate them from each other. We updated all outline styles to use a uniform dash style.
People rarely used the heading level interface
Most of our accessibility designers preferred to edit heading levels on the stamp itself rather than use the component property drop-down. Since the scope of many design features is for components or small parts of a page, a heading level selector is too restrictive. Designations such h^n or h+1 might be used to indicate that the heading level should be one level deeper than whatever heading level precedes it. We replaced this selector with an open text property, leaving the heading level to the user’s preference.
Heading stamps had poor cognitive accessibility
Colleagues with ADHD or dyslexia found it difficult to discern the level of a heading stamp. Even though each level had dots on the left to help with this, the primary visual differentiation between levels came from the number itself. We addressed this by making the “h” lower case and adding subtle spacing around it, which helped the number stand out.
Size doesn’t matter (and makes other issues worse)
Drawing from WCAG Success Criteria 2.5.5: Target Size, we set stamp height to 44 pixels. The assumption that a component on a Figma canvas could or should be a ‘touch target’ caused more problems than it solved.
Placing a lot of large stamps on a complex design can result in overlap and quickly become hard to read, diminishing the kit’s usefulness. And given the ease of zooming in on the canvas, it was just as easy to achieve ‘touch target size’ that way if needed. To give things a bit more room to breathe, we reduced stamp height to 32px.
Refining the user experience
Making sure everyone can follow along
The end-users of accessibility annotations are the people reading them — developers and testers. No matter how well-designed the components are, we’re not solving any problems if the accessibility documentation isn’t easy to follow.
While we worked with developers often to test our assumptions, there will always be those who were new to our annotation process. With them in mind, we created a few utilities to ensure an intuitive and legible experience.
Pro-tip: No tool or kit is a substitute for the shared understanding that comes from talking to each other. We avoided a staggering number of miscommunications, errors, and money wasted trying to fix them by meeting with designers and developers to review our finished annotations.
Safeguarding against data loss
One of the kit’s early pain points was that our rapid iteration was leading to data loss. Unless we took great care when updating this Figma asset library, some of the changes we made to the components would erase annotations made by our testers.
Since annotations are one of our most important deliverables, the risk of them being deleted was a wake-up call. Without this tool to create consistent documentation, we wouldn’t be able to tackle things like scalable process or training. And if our updates to the tool erased data, adoption could suffer enough to bury the project.
Fortunately, we found a solution before this caused too much pain. To prevent data loss, we implemented Visual Regression Testing (VRT) for every stamp component. VRT is an internal library tool used to catch breaking changes, such as loss of data. They provide an opportunity for a human review to check that the update will not break an instance already consumed by a team.
A brand-new annotation kit
It was time to take everything we had learned along the way and put it together. Leveraging new Figma features such as component properties, nesting, variables, and improved auto-layout features, we built a new kit from the ground up.
- Increased number of formats for all stamps, and a streamlined design for rare use cases such as headings, focus order, and reading order stamps that have notes attached.
- Many Input stamp variants with built-in parameters. This saved a lot of time and we were no longer having to look up semantics for different types of input. Building these into the kit also helped us educate designers about how their forms work.
- We avoided fixed values so that fonts and dimensions could be changed by anyone who wants to customize the kit.
There are many other things we could add, but it might be more illuminating to just let you see it in action:
This kit helped us do everything we set out to do, and more. From the start, however, we wanted to craft something that might help others outside of CVS Health. We have been fortunate to follow and learn from many others, so we felt it important to return the favor. Our hope is that the Design and Accessibility disciplines use and improve on them so that the internet as a whole may become more accessible.
This accessibility annotation kit focuses on everyone, from those creating annotations to those consuming them. It’s highly configurable and easy to use — even for novices. To me, its best feature is how it helps build accessibility maturity through common vocabulary and patterns for colleagues across disciplines.
— Charles Hall
Domain Expert, Inclusive Design & Accessibility
Invited Expert, W3C Accessibility Guidelines Working Group
We’re just getting started
Our accessibility annotation kit for the Web was an overnight hit that became a massive success. Even so, we found that using it for iOS app designs was consistently leading to inaccessible experiences. Accessibility for both platforms is fundamentally different.
The way that elements are structured on a page, the accessibility APIs that assistive technologies interact with (and therefore the assistive technologies themselves) all behave uniquely. These all contribute to a set of expectations and experiences very different from the web, especially for disabled people.
Soon after releasing our internal beta of this kit, we began working on one of the first accessibility annotation kits for the iOS platform. We plan to release it in the coming months.
Thanks for reading and stay tuned for more!
© 2023 CVS Health and/or one of its affiliates. All rights reserved.
