Annotating designs using common language

Posted on Tuesday, 23 September 2025 by Craig Abbott in Design and development

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:

• Contrast & Accessibility Checker, by Stark
• Accessibility Assistant, by Microsoft
• A11y Annotation Kit, by Indeed
• axe for Designers, by Deque

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:

   • Browsing with a mouse? For example, clicking, dragging or hovering.
   • Browsing with a screen reader, for example, listening to text descriptions.
   • Browsing with a keyboard? For example, using Tab, Space or Enter keys.
   • Browsing with speech recognition? For example, saying "click button" or "press tab".

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

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

Ambiguous links

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

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

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

Skip links

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:

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:

Page titles

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

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

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

Icons

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

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

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

• Accessibility Foundations
• Design patterns and WCAG
• Gherkin Reference Documentation

Next steps

For more information about accessible design, read about Accessible Design Systems or find out about how our design review service can help you identify design issues in your websites, mobile applications, design systems, and other products and services.