Web Accessibility Annotation Kit
Accessibility annotations help capture design intent that cannot be conveyed through visual design alone. This tool can help prevent many accessibility issues before your designs are built. After nearly two years testing and refining this annotation kit, 65 design teams across CVS Health have used it to make 150,000+ annotations within 1,100+ design files.
However, like any tool, it can also create more issues when used improperly. It’s best used by those with existing knowledge about WCAG, WAI-ARIA, form semantics, focus order, and other accessibility topics. In the future, we intend to add some learning materials for those who are new to accessibility.
Important Note: This kit is made specifically for web experiences. It can create issues when used on designs for mobile platforms. We have developed a separate annotation kit for iOS which will be published soon.
- Figma Community: Web Accessibility Annotation Kit by CVS Health® Inclusive Design
- Medium: Announcing a new Web Accessibility Annotation Kit
- Medium: Behind the scenes of creating a new Web Accessibility Annotation Kit
- Follow CVS Health on the Figma Community
Included in this kit are components for the following types of accessibility annotations:
- Button - Interactive elements that perform an action such as submitting a form or opening a dialog.
- Heading - Semantic levels within a page’s section hierarchy.
- Image - Describe informative or mark decorative images.
- Landmark - An important section of a page.
- Link - Interactive elements that navigate to web pages, files, or anything that changes a URL.
- Input - Fields and controls for forms to accept data from users.
- Focus Order - A sequential order of focusable components that preserves meaning and operability.
- Reading Order - The sequential order in which assistive technology will read content.
- Note - Any details that don’t fit into the other annotation categories.
- Utilities - Several references to aid in the developer experience.
Each type has its own color, icon, text label, outline, and shadow. These signifiers help to identify and differentiate them from one another as well as the designs they overlay.
Since the word “annotations” may refer to the individual components as well as the documentation itself, we use the word “stamp” to refer to the different types of components.
Pin Stamps point to parts of a design that are above, below, left, right, or center (no pin). This orientation can be set using the “Stamp position” component property.
Lasso Stamps highlight an area of the design. This is useful for outlining landmarks or components such as linked cards. Like Pin Stamps, labels position can be changed to reduce risk of overlapping other stamps or important parts of a design.
Details components are numbered notes in the margins around a design that always correspond to numbers used by Pin or Lasso Stamps. The content of these stamps can include interface behavior, code semantics, ARIA, and so on.
Stamps with notes are variants that help with complex use cases. Heading, focus order, and reading order use numbers differently than the other stamps (to communicate a heading level or linear progression). This format preserves that meaning while allowing a Detail component to be associated with it.
This kit can be used many different ways. These are the ways we have found to be most helpful and intuitive both to create annotations and to consume them.
When a design elements just need a simple identifier, use a Pin or Lasso Stamp to label the element with what it should be. For example, a heading, link, button, or decorative image.
Screenshot from Wikipedia.org and shared under a CC BY-SA 4.0 license.
When a design requires more accessibility information than what’s included on the stamp label (e.g. landmarks, inputs, or informative images), activate the number property for the Pin or Lasso stamp and place a Detail component with a matching number in the margins next to the design.
Screenshot from Wikipedia.org and shared under a CC BY-SA 4.0 license.
Where possible, try to place stamps outside the frame, with the “pin” or “lasso” outline referencing the appropriate design element. With closer proximity to any associated Detail components in the margins, developers can read the annotations quickly without missing any.
The best annotation kit is as only as useful as our annotations are legible. Here are some recommended techniques for keeping our documentation easy to read and free of overwhelming clutter.
Large features and full pages may contain hundreds of elements to annotate. One strategy to help keep things legible is to clone the page/frame and place only one or two types of annotation on each.
Screenshot from Wikipedia.org and shared under a CC BY-SA 4.0 license.
There are many navigation and search landmarks in this example, but they can be discerned. If you were to add stamps for every button, link, heading, input, image in this frame, as well as focus order, it would become visually overwhelming and unhelpful.
Interface complexity isn’t often distributed equally. When annotating parts of a design that are more complex, there may be excessive overlap between stamps, stamps nested within one another, and more Detail components in the margins than the margins have space for. This can be alleviated by annotating complex patterns in their own frame.
Interface patterns such as navigation menus and definition lists often have repeated elements. If there’s no variation for each repeated element, it may not be necessary to annotate every single one—though it is best to make a note of this shortcut to avoid confusion.
This may also be the case with designs across viewports. If a responsive design is delivered with mockups based on screen size, the accessibility annotations might be the same for all of them. In this case, you may not need to redundantly annotate each.
This resource was built with organizations in mind. Styles can be easily changed to your preference. We’ve implemented Visual Regression Tests (VRTs) to help ensure that components don’t break and no data is lost when publishing your own library updates.
This resource is designed to be published as a Figma library to provide a single set of annotations for your organization or team. You can then use the kit by managing the libraries in your design files.
If you are not on a paid Figma plan, you can still use the kit by copying and pasting the components locally into your design file.
All text styles, color styles, and variables have an underscore prefix (e.g. “_Button”) so that these are not published to your organization.
All the colors and text styles used in this kit are stored locally. You can access local styles for Text, Color, and the drop shadow Effect used for annotation stamps in the right sidebar when nothing is selected, or from the style picker.
After updating Text, Color, or Effect styles, your changes should be immediately reflected anywhere this kit is used.
Note: It is highly recommended that you ensure any new colors maintain a 4.5:1 contrast ratio to help ensure everyone using the kit and reading annotations can perceive them.
For more help, visit create color, text, effect and layout grid styles on Figma.com.
Unique vector icons are used for each type of annotation and are stored as components on this page. These can be changed in the Internal library components frame on the far right side of the -- Customize this kit -- page.
Any updates will be immediately reflected anywhere this kit is used.
If you are publishing this kit as a Figma asset Library, we recommend that any updates you make to the kit components be done carefully. Customizations that are more complex than changing styles or swapping out icons, for example, may affect components in a way that causes data loss.
In other words, when you update a core Stamp or Detail component and publish those changes to the Library itself, it’s possible that any existing annotations which were created using this Kit could lose some of the data you’ve entered. For example, incremented Stamp numbers might be reset, or custom properties in the Detail components might be reset.
To help prevent this, we’ve created a Visual Regression Testing (VRT) tool for every component in the kit.
When making changes to a component, it is highly recommended you use Figma branching. This gives you the ability to compare changes between the main file and the branch.
The VRTs provide an opportunity for a human review to check that the update will not break an instance already consumed by a team. If the reflection of the VRT is not what you want consumers to receive, you are able to make corrective changes before publishing that update.
In each VRT:
- All number properties in VRTs are set to
333. - All text properties in VRTs are set to
override override... - All boolean properties in VRTs are toggled (not the default value).
- All Pin, Lasso and Detail components have been resized.
When comparing changes during a branch review, if these overrides have been unexpectedly changed between the Before view and Latest view, your changes may break existing annotations in other files.
This kit is brought to you by the CVS Health® Inclusive Design team.
- Jan Maarten, Sr. Accessibility Designer
- Daniel Henderson-Ede, Sr. Accessibility Designer
- Kevin Oliveira, Sr. Accessibility Designer