Create accessible designs using the Figma A11y Annotation kit

Paul Adam
Designing Atlassian
6 min readDec 3, 2021


Example showing heading and alt text annotations.
Design annotated with Heading and Image Alt Text properties

Accessible experiences don’t design themselves. If designers don’t annotate their designs with accessibility properties and behaviors then developers won’t code an accessible experience… and we’ve failed to shift accessibility to the left in the software development life cycle (SDLC).

Shifting Accessibility to the left in the Software Development Life Cycle (SDLC)

Software Development Life Cycle flow chart showing stages Plan > Design > Develop > Test > Deploy and Shift Accessibility Left with an arrow pointing to the left side of the SDLC
The Shift Left concept moves accessibility from the end stage of the SDLC to the beginning

The traditional way of managing accessibility has been to add it at the end of the software development lifecycle after all the design and development work has been completed. The accessibility team or QA testing team is usually involved at the end of a project after the site or app has been launched — when the team suddenly realizes accessibility was part of the legal or vendor software requirements.

Because the site was not designed with accessibility in mind the subsequent audit report generated by the accessibility testing team is huge, possibly highlighting more than 100 WCAG failures. At the end of the project, it’s many times more difficult, expensive, and time-consuming to fix 100 accessibility issues, many of which require design changes rather than simple code fixes.

Shift Left upends the traditional way of adding accessibility at the end of a project and instead requires the accessibility responsibilities to shift to the initial stages of software development or the left side of the SDLC. Therefore it’s everyone's responsibility to incorporate accessibility from the earliest stages of planning, design, coding, through to prototyping.

Project managers must define the accessibility requirements for the site or app and plan for the early, middle, and late stages of accessibility reviews and testing. Designers need to design not just the visual, mouse-based experience but also the experience for blind, screen reader users and keyboard-only users. Designers need to annotate their designs and mockups with accessibility properties and behavior like image alt text, icon button names, and keyboard operation so developers know exactly how to code the accessible experience. Developers need to implement the accessibility requirements and behaviors as defined by the designers and their annotated design files.

Colour Contrast Analyser showing orange on white has a 1.9:1 contrast ratio which fails all WCAG success criteria for contrast
Colour Contrast Analyser showing the orange star icons fail contrast ratio requirements for Non-text Contrast

As part of shifting left, designers and developers need to conduct their own accessibility testing to find and fix issues before its reviewed by the accessibility QA team.

Designers can use contrast testing tools like the Colour Contrast Analyser or Figma accessibility testing plugins.

Developers must ensure they’re shipping clean, valid, accessible code and should use browser extensions like axe DevTools and validate their code with the W3C validator.

When everyone is responsible for accessibility most issues will be identified and fixed during the normal stages of design and development.

axe DevTools showing 79 issues and an image failure is highlighted
axe DevTools displaying 79 total accessibility issues and highlighting the first image alt text failure

Add accessibility properties and behaviors to your Figma designs using the A11y Annotation Kit from Indeed. The basic accessibility properties are Heading Levels, Image Alt Text, and Accessible Names for Icon Buttons.

Getting started with the Figma A11y Annotation kit from Indeed

Accessibility Annotation Kit community file showing Duplicate into drafts process
Duplicate the A11y Annotation Kit into your Figma Drafts

Find a design that needs accessibility annotations and then get the A11y Annotation Kit from Figma Community Files. Duplicate the a11y annotation kit into your Figma drafts.

Example of alt text annotations for a decorative paperplane icon and 2 image buttons
Example of image and button Alt text annotations

Read the About, How to, and review the example annotation pages in the kit to learn how to annotate and see example annotations.

How to annotate a Design using the Kit

  1. Open a design file that requires accessibility annotations.
Confluence home page screenshot that we’ll be annotating
We will annotate the Confluence Cloud Home page with accessibility properties

2. Open the A11y Annotation Kit > Assets page and find some accessibility callouts to copy and paste into the design file.

Headings callouts showing H1 H2 H3 H4 etc with arrows pointing in 4 directions
Heading level annotation callouts on the Assets page

3. Copy a heading callout (in this instance, we’ll use H1) and paste it into the design file to specify what text needs to be coded as the <h1> element.

H1 callout shown selected for copy/paste
Select and Copy the H1 callout

The first heading element within the <main> content area needs to be defined as an <h1>.

H1 callout points to the Spaces text
Spaces has been defined as an H1 Heading Level 1 element

More heading level annotations can easily be generated by duplicating the first callout (⌘ + D) then dragging to the other headings and changing the Heading Level in the Design properties panel.

H1, H2, and H3 heading callouts shown on the heading and subheadings
Heading callouts duplicated and levels adjusted for subheading text

4. Annotate the image alt text into the design so developers know what to code for the accessible names of images and buttons.

Buttons and Image annotation callouts from the assets page
Find the Buttons and Image callouts in the Assets page of the A11y Annotation Kit

5. Define what images are pure decoration and should be ignored by screen reader users. If decorative images are not ignored i.e. with <img alt=””> then screen readers may speak the image filename or an incorrect alt text may be written into the alt attribute value by the developer.

Copy the Alt=”” callout and paste it above the first decorative image in the design which is the accessibility icon symbol. These images in the Spaces links are decorative because the links already have sufficient visible text to serve as their accessible names. If the accessibility icon image is not defined using <img alt=””>, the screen reader may duplicate the alt text when it focuses on the link, e.g. the screen reader might speak “Accessibility Accessibility, Link” repeating the word Accessibility because it was incorrectly written as alt text for the icon image. Duplicate the Alt=”” callout and drag it to all other decorative images in the design.

Alt=”” callouts pointing to the decorative images
Decorative/redundant icon images defined with Alt=”” so they’re ignored by screen readers

6. Define alt text for informative images and icon buttons. The star icons visually convey to sighted users which spaces have been added to the Starred list. This is how to convey to screen reader users an informative alt text for the star icons.

Alt=”Starred” callouts pointing to the star icons
Informative star icon images annotated with Alt=”Starred”

Now for the Alt=”Starred” annotations, the screen reader will speak “Accessibility Starred, Link” and “Paul Adam Starred, Link” for the two links that have star icons.

7. Define the alt text/accessible name for the Create/+ icon button.

Create button shown with a C tooltip displayed
Create button showing the keyboard shortcut letter “C” as a tooltip

The Create button normally doesn’t need an accessibility annotation because it shows the visible label text “Create”, however, the Create button also displays a tooltip shortcut letter “C” to let sighted users know they can type the letter C to activate the create button. Include that shortcut letter as part of the name spoken by screen readers so users know that C works as the shortcut key.

Another reason to define the accessible name of the create button is that it also turns into a + icon button in responsive views at narrow screen sizes. Annotating the button label text for the + button ensures that screen readers will not hear “Plus, button” spoken as the name of the Create button.

Callout reads Button label=”Create, C” for the + button
+ icon button’s label defined as “Create, C”

There is a lot more work to be done to include all the required accessibility properties and behaviors into our annotations before we deliver them to developers. The hope is that this post will help you get started on the accessibility annotation process and highlight the importance of shifting accessibility left in the software development life cycle.

Below is a screenshot of a completed accessibility annotations file that goes beyond annotating just images and headings.

Final annotated example with many accessibility callouts defining all accessibility properties of the design
Final Completed Accessibility Annotations Example