In most organisations, design documentation often includes annotations, but accessibility-specific ones are still rare. That’s a missed opportunity. Annotating designs for accessibility helps everyone involved understand what needs to be built, tested, and maintained.

Using a common language that designers, developers, and quality assurance (QA) teams all understand is essential so that information doesn't get lost in translation, especially during the hand-off between design and development.

There are already some great Figma plugins and libraries to help, such as:

These tools can make accessibility annotations easier to manage, but they’re just the starting point. What really matters is knowing what to annotate and how to do it clearly and consistently using language everyone understands.

Why accessibility annotations matter

Most of the time, things aren’t inaccessible because someone deliberately designed them to be that way. They become inaccessible because multiple people throughout the process didn’t consider accessibility. In the fast-paced world of product delivery, if nobody considers accessibility, the product will simply be shipped without it.

As an example, if the designer does not provide text descriptions for editorial images, the development team will usually do one of three things:

  1. Leave the alt attribute out altogether, so screen readers fall back to announcing the image file name or URL
  2. Provide a text description themselves, which may or may not accurately describe the image in its context
  3. Use an empty alt attribute, effectively marking an image as decorative when it shouldn't be

So, by annotating our designs, we help to fill in those gaps for the development team. We clarify our design intent, reduce ambiguity, and save the whole team time by avoiding expensive re-designs, rebuilds, or last-minute bug fixes.

What to annotate

Annotate anything that could affect accessibility or usability, especially when it isn’t obvious just by looking at the design.

For example:

  • Action labels: for elements like buttons and links
  • Content structure: like heading levels and lists
  • Error suggestions: for elements like form inputs with error messages
  • Keyboard functionality: like focus order and visible focus styles, keyboard accessibility, and skip links
  • Layout: how elements behave at different viewport sizes or breakpoints
  • Multimedia alternatives: like audio descriptions, captions and transcripts for inclusive video
  • Page titles: which accurately represent the content and orientate the user
  • Reading order: for complex layouts or grouped elements
  • States: for changes of state such as disabled, invalid, loading, expanded and collapsed
  • Text descriptions: for elements like images and icons
  • Timings: like durations, time limits, and session time outs

Deciding what's important

To decide what's important to annotate for developers, look at each element and ask three questions:

  1. What different outcomes are possible from interacting with this element?

    • Does it change state? For example, selected, expanded or collapsed.
    • Could something go wrong? For example, validation errors.
    • Does it change the current context for the user? For example, opening a modal or navigating to a different page.
  2. How might different people achieve each outcome?

    Are they:

  3. What isn’t immediately clear just by looking at the design?

    • Are icons ambiguous? For example, an "X" icon could represent "clear", "remove", or "close" actions.
    • Is the content structure ambiguous? For example, different heading levels could look similar in size.
    • Is content ordering ambiguous? For example, a sidebar could be read out before or after the main content.

The current challenge with accessibility annotation tools

The biggest challenge we see with most of the current accessibility annotation tools, is that they usually require the person doing the annotations to have a strong knowledge of HTML and accessibility.

To be honest, although most accessibility annotation tools are built to use in Figma, they often feel like they're designed for web accessibility specialists or developers, not designers.

For example, to use most accessibility annotation tools, you usually need to know technical implementation details, like:

  • HTML elements
  • Semantic landmarks and roles
  • Standardised autocomplete values
  • WAI-ARIA attributes and roles

If you're a designer, it's unlikely your knowledge on HTML semantics or WAI-ARIA will be as good as the developer who you're handing over to. So, trying to annotate these things in your design can feel quite daunting!

An easier way to annotate your designs

Behaviours and expected outcomes

In software development, it's common to build and test things using a methodology called behaviour driven development (BDD). If you're not familiar with it, the idea is that you create tests for a computer to carry out, but written in a way where they also make sense to any humans reading them.

BDD describes the needs of the people using the application, then outlines possible scenarios. This way, when the application is built, it behaves as expected.

Scenarios may vary slightly in their format, but they're usually recognisable because of the words "given", "when" and "then". This is often referred to as Gherkin syntax, made popular by the testing framework Cucumber.

For example:

Feature: Sign in
    As a registered user
    I want to be able to sign in to my account
    So that I can view my account information
    
    Scenario:
        Given I am on the sign in page
        When I enter my username and password correctly
        And I click the sign in button
        Then I should navigate to my account

The point of BDD and the frameworks which enable it, is that it helps to facilitate collaboration between multi-disciplinary teams, which likely have a mix of technical and non-technical roles.

Using the same language

In user experience (UX) design, whether designing interactions or conducting usability tests, designers observe and anticipate user behaviour all the time. So, if designers are thinking about behaviours, and developers and testers are also thinking about behaviours, then it makes sense for us all to just use the same language!

As designers, using a similar format is an easy way to write up expected outcomes for accessibility, without needing to know the technical implementation to actually achieve it.

You might not need a "given" statement, because the design you're annotating probably sets the scene, but using the following pattern, you can quickly set expectations for developers:

When: describe action and context
Then: describe expected outcome

For example:

When I focus the pencil icon using a screen reader Then it should announce edit address

You can also use a table if there are a few different outcomes. For example:

When I enter a postcode And the format is invalid Then it should show the correct error message

Description Outcome
Blank Enter a postcode
Wrong length Enter a postcode between 5 and 7 characters long
Special characters Enter a postcode using only numbers and letters
Does not exist Enter a postcode which exists in the UK

Examples

Below is a set of examples showing how to use this method to annotate different elements in your designs.

Content structure

Ambiguous buttons

When I focus the hamburger button using a screen reader Then it should announce navigation menu

When I focus the read more link using a screen reader Then it should announce the visible read more label And it should also announce the associated blog post title

Heading levels

When I navigate the headings using screen reader Then it should announce the correct heading levels

Description Outcome
Our services level 1
Experience level 2
Knowledge level 2
Strategy level 2

Ambiguous unordered lists

When I focus the action menu using a screen reader Then it should announce that it's a list with four items

Ambiguous ordered lists

When I navigate the history timeline Then it should announce it's an ordered list with five items

Error suggestions

When I enter an invalid email And I submit the sign-up form Then it should show the error variant And the correct error message should be displayed

Description Outcome
Email blank Enter your email
Email missing "@" character Your email must include an "@" character
Email missing "." character Your email must include a "." character

Keyboard functionality

Focus order

When I navigate the dialog using a keyboard Then the focus order should follow the correct sequence

  1. Close button
  2. Cancel button
  3. Delete button

Focus styles

When I focus the delete button using a keyboard Then the focus variant should be visible

When I navigate the page using a keyboard Then the skip link should be the first element to receive focus

Keystrokes

When I re-order the drag-and-drop sortable list using a keyboard Then it should respond to the following keystrokes:

Description Outcome
Tab Activates / deactivates list
Space (released) Grabs highlighted item
Space (grabbed) Releases item in current position
Esc Releases item in previous position
Up arrow (released) Highlights previous item
Up arrow (grabbed) Moves item up 1 level
Down arrow (released) Highlights next item
Down arrow (grabbed) Moves item down 1 level

Layout

When I zoom in my browser And there is not enough room for the navigation links Then the navigation menu should switch to the mobile variant

Multimedia alternatives

When I select the audio descriptions button Then the video should switch to the audio described version

When I select the closed captions button Then the captions should be turned on And they should be in sync with the video

When I select the transcript link Then the transcript side-panel should open And the transcript should be scrollable

Multimedia assets can be found at the following links:

Description Link
Original version sharepoint/video.mp4
Audio described version sharepoint/video-audio-described.mp4
Captions sharepoint/captions.srt
Transcript sharepoint/transcript.odf

Page titles

When I view the page tab in my browser Then it should show the correct page title

Description Outcome
Home page Tetralogical
About page About – Tetralogical
Services page Services – Tetralogical
Blog page Blog – Tetralogical

Reading order

When I navigate the main page content using a screen reader Then it should announce content in the correct order

  1. Blog post content
  2. Related posts
  3. Sign up to our mailing list

States

Error identification

When I make a mistake in a text input And I am using a screen reader Then it should announce there's an error And it should show the error variant

Disabled

When I focus the button using a screen reader And it's in a disabled state Then it should announce that it's disabled

Loading

When I select load more search results using a screen reader Then it should announce the correct status updates

Description Outcome
Loading start Loading more search results
Loading end Search results updated

Expanding and collapsing

When I focus the disclosure element using a screen reader Then it should announce it's visible label And it should announce whether it's expanded or collapsed

Text descriptions

Images

When I focus images using a screen reader Then it should announce the correct text description

Description Outcome
Logo TetraLogical
Experience icon Experience: five people, each made up of a circle for a head and a semicircle for a body. Four are bright purple and positioned randomly around a fifth at the centre who is bright orange and has three beams radiating from their head as they share thoughts and ideas with others.
Knowledge icon Knowledge: two people, each made up of a circle for a head and a semicircle for a body. One is bright pink and the other bright purple, above them is a speech bubble with an orange spark of a shared idea inside.

Icons

When I focus icons using a screen reader Then it should announce the correct text description

Description Outcome
"x" icon Close
"i" icon More information about privacy settings

Timings

Durations

When I receive a new message Then then it should show the toast message "New message received!" And after five seconds it should disappear automatically

Time limits

When I am using a screen reader But I have not moved my mouse or pressed a key for twenty minutes Then the session timeout modal should appear And it should announce you're about to be signed out And it should announce the remaining time at the correct intervals

Description Outcome
45 seconds 45 seconds remaining, press any key to stay signed in
30 seconds 30 seconds remaining, press any key to stay signed in
15 seconds 15 seconds remaining, press any key to stay signed in
10 seconds 10 seconds remaining
5 seconds 5 seconds remaining
0 seconds You have been signed out. Redirecting you to the sign in page.

Final thoughts

Designing isn’t just about visuals; it’s also about creating the experience and the outcomes people should have.

You don’t need to annotate every single element. That would quickly get tedious! Annotate only elements that impact someone’s ability to navigate, perceive, or understand the interface, especially if those impacts aren’t obvious just by looking at the design.

You also don't need to learn or write perfect Gherkin syntax. But, if you just make it clear that, "when I do this thing, then I expect this to happen", it's already a lot more familiar. By using consistent language to describe designs and focusing on outcomes, you can clearly express design intent while leaving technical implementation to developers.

Further reading

Next steps

For more information about accessible design, read about Accessible Design Systems.