A Designer’s Guide to Documenting Accessibility & User Interactions

Accessibility is unfortunately still an afterthought on many projects. User interaction and accessibility requirements are poorly documented, at best. Or forgotten, when handing over designs to developer teams. And fixing it later costs a LOT more than building it right to begin with. Great documentation helps teams implement accessibility requirements the right way. I will tell you why, what and how designers can document different aspects of accessibility and user interactions requirements, to build better more inclusive products. I also added a checklist at the end of the article to help you remember all of this.

This is the article version of a talk I presented on March 16 at axe-con. (watch the replay of my talk page). It was updated on Sept 7 2022 , for Web Accessibility in Mind conference, to reflect the structure and content of a new version of the talk. You can also check the slides.

Why fix it later, when you could do it right to start with?

Broken glasses fixed with shiny duct tape and glueA lot of sites were not designed and developed with accessibility needs in mind. As designers, a lot of us think that “accessibility is the job of the developer team”. Accessibility becomes an afterthought for a lot of projects. Companies launch inaccessible tools, sites, services.

Eventually, someone will complain about this. Maybe the site even gets sued. It circles back to the team. And now they have “fix” the accessibility issues. But, it’s often too late. When the site was not designed, developed with accessibility in mind, it’s harder to correct. And way more expensive as well. A little bit like in this picture: they end up putting duct tape on broken glasses.

My question is: why fix it, when you could design and build it right to start with?

This is why we need to bring accessibility awareness earlier on in the project. Good guidelines and documentation can help us achieve that. They can help identify and fix accessibility issues, earlier in the project. Accessibility becomes part of the “project normal design and development phases“. It’s not an afterthought anymore.

How and Where should I document accessibility?

Bring accessibility annotations to mockups and design documentation

Let’s talk about my team. After all, the goal of this article (and talk) is to share what I do. So that you can get inspired and find your own way.  We use Sketch and my developers have access to the Sketch mockups. I have 2 different Sketch files:

  • A “component documentation” which is our design system where each component is described. This one is used as a Sketch library
  • A “page documentation” : the components are put together on pages

In both those files, I document using a lot of annotations. I document using annotations on both component and page documentation.

Documentation at component level

Here is an example of a detailed documentation for a search filter at different states.

Detailed component documentation with annotations.

On the left: an example of a component with different states. On the right: my component symbols.

I put design annotations directly on the component mockup to help developers understand how this works for interactions, but also accessibility. Those are the little arrows in pink and the keyboard annotations.

I do that mostly because people don’t like to read specs and backlogs. But they might (yes might) look at my design files. I created some Sketch symbols for such annotations. Those are the right part of the example. I have arrows, numbers, boxes, keystrokes and some mouse/touch interactions.

Documentation at page level

I then re-use my components to build different pages. Sometimes, I also have annotations directly on a second mockup at page level as well.

Page documentation: annotations directly at page level when needed

In this example I have the regular page mockup, and the same one with hot pink comments for my developer team

Hot tip: make sure the annotation style is different from the page style. This is why mine are magenta. I want to avoid developers implementing the annotations as part of the product by mistake. And, yes, I saw this happen before.

Documentation using numbers and margin comments

While researching for this talk, I stumbled upon Karen Hawkins “Accessibility Annotation Examples“.Accessibility annotation in red with the (AR) prefix in the right margin, linked to small numbers on the mockup to indicate what is annotatedI find this format interesting as well. She puts the mockup on the left of the page, with little numbers on certain areas. On the right, she has detailed documentation for each number. The design annotations are in dark. And the accessibility requirements are in red, with a little (AR) prefix.

Determine the best format with the team

My number one advice: if you want documentation to be useful and used, ask the team about what would work for them. There are many different formats that you could use to document. Here are a few idea:

For me, it’s all about the best format for YOUR team. This has to be an open discussion.

Documentation is no substitute  for communication

There are different styles and ways to document. Come up with your own and test what works for YOUR team. But remember one thing: Documentation is NOT a substitute for talking to people!!!!

It’s still important to present the documentation in person if you can. In our team, we have weekly meetings. Developers show demos. I show and discuss such documentation and specifications.

It is usually a discussion then, with the team, on what is possible, what is not, how we might implement those, etc.

What exactly can or should designers document?

Let’s now dig into actual examples of documentation: what exactly can or should designers document? To help you process this, I’ve split those into 4 different categories: Visual design, Interaction, Wayfinding and “Announced Content and Markup”.

Documenting Visual Design

Visual design, especially colors is often the first thing that comes to mind when we think about design documentation.

A simple 2 combinations color documentation

Let’s start with Visual design. The first thing designers can document are the colors and the color palette. If you need help creating palettes, check Tips to Create an Accessible and Contrasted Color Palette.Color palette with AA and AAA levels for some color combinationsHere is an example of how I used to document this. For each color in the palette, I match it with a white background. And documented if it passes the AA or AAA contrast ratio check for regular or big text. This is a start, but sometimes I need more granularity.

A color matrix to document all combinations

When I need something more complicated, I use a color matrix tool like this one.Color matrix with the same colors on x and y axes and their color contrast ratio when used togetherHere we have the same colors on the horizontal and vertical axis. The intersection of both shows their color ratio when paired together . This helps me know if I can pair those 2 colors together for different ratios: 3:1 4:5,… For example: I should not use that yellow as text on which background, but I can pair it as text for darker grey. I can then put this matrix in the project, to let other designers know color combinations they can and should not use.

Not all designers might be familiar with the ratios, AA / AAA meaning and small vs big text concept. You still need to explain this somewhere.  Or put some links to external sources. You could use Geri’s WCAG for Designers documentation or the accessguide page on contrasts. For more tools check “Color accessibility: tools and resources to help you design inclusive products“.

Documenting Interactions

The next category is the documentation of interactions: how is a user going to interact with those components and pages?

Interactions states and statuses

Let’s talk about interactions. For interactive components, the first thing I try to document is the different states. Documentation for button states and form elementsIn my example I document different button states: default, hover, focus, active, disabled. You could also have extra “non” HTML official states like “loading”. For checkboxes I have: default, focus, checked, disabled, disabled checked, indeterminate, disabled indeterminate. This is done at component level.

For form inputs, at component level, I have some generic classics: default, focus, filled, read only (or disabled)

But I could have some extra statuses, for example:

  • Error
  • Success
  • Information

For those, I don’t just use color, but also some text and icons (so that the color is not the only way to convey information)

At page level, where the component is used, I often need to specify more clearly.  On the right, I have an example of a year input used in a filter.  I document:

  • What triggers the error (= error case)
  • What the exact message (copy) should be.

Interaction flow to document mouse and keyboard input

For complex components with many interactions, I build “interaction flows”. This documents how these components should work, when there are different interactions. Let’s start with mouse interaction.Component documentation with mouse and keyboard navigation interaction flowIn this example, I have a filter with checkboxes. I documented step by step what happens when a user:

  • Opens the filter,
  • Hovers an element,
  • Checks filter box,
  • Hits the apply button, etc.

On top of mouse interaction, I also document keyboard interaction. So I end up with a similar flow, that will also show keyboard navigation in this component:

  • How to open the component (enter/space), close it (esc)
  • How to navigate across the elements (up/down key)
  • How to check a box
  • etc.

If the component has some keyboard shortcuts (mine don’t), this would be a nice place to document that as well.

Here are a few resources to help you get started with keyboard interactions

A little reminder to help you document keyboard navigation:

  • Tab lets people jump between sections
  • Arrow key helps navigate inside the component
  • Space / enter activates the element

Alternatives for complex gestures

Providing alternatives for complex gestures is an accessibility and usability best practice. An example of this is the swipe right” to archive feature in gmail.Complex gestion and 2 alternatives for the archive feature of gmailIf I were to document alternatives for gmail, I could do something like this. I would document the complex gesture with a mockup that shows the swipe right to archive.

Then I would document alternatives:

  • A long press on the mail to show the toolbar, then press the archive icon
  • Open the mail, then press the icon at the top

Zoom behavior

For complex responsive pages, you could also document the “zoom” behavior. I’ll be honest with you.

Since I often provide responsive web design guidelines, I never went into THAT level of details for websites. I ask developer teams to NOT block the zoom behavior (and height). And we test our sites with different resolution and browser zoom levels.

But I think this can be really useful for native apps.Example of a natif app at zomm 100% and 200%This is an example for Goulven Baron at Maif. He documented how the mobile view behaves at 100% on the left and at 200% zoom.

Reduced motion and play/pause buttons

One aspect of design that is quite tricky to document is animations and transitions. There are accessibility best practices for those as well. Some animations and transitions can trigger motion sickness to some users. I’m one of those by the way.

You can use the prefers-reduced-motion media query to provide an alternative version for people who prefer less motion. If you want to learn more about the topic, check the section “Building Accessible and Inclusive Animations” of my talk on CSS animations and UX.My website and the macbook option to reduce motion that will remove some of the animationsOn my homepage for example I have 2 animations. The fox, sushi and coffee float around my head. And if you scroll down, I have a growing plant when you reach the “I help people grow” part. If the user chooses the reduce motion option in the operating system, I stop the animation around my head. And the plant growth becomes a smooth less triggering fade in.

How do you document this? Well…Animations are often something that is built in direct collaboration and fine tuned in the browser.

For those sorts of things, I think you need to have a discussion with the dev team directly.

Also, don’t forget to have some play/pause buttons in your interface, if you have videos and sliders. Let the users control those!

User flow to document interaction between pages

One last level of documentation is “interactions across pages”.Boxes and arrows graph showing the user flow and the wireflow with actual mockups instead of the boxesUser flows (on the left) are kind of “step by step” boxes and arrow graphs that document how someone accomplishes a task. They list pages, views, branchings, … They are usually built at the beginning of the project to help plan those pages and flows.

Screen flows (on the right) are kind of the same. But instead of boxes for pages, I put the real interface mockups. I build those at the end, once we went through usability testing, refinement and have mockups. Both help the dev team understand how the user will navigate across the whole interface.

Such documentation can help with accessibility to plan:

  • Transitions between pages. Especially in single page applications or mobile apps.
  • Alerts or messages that might appear and stay on top of the page  even if users got to another one.
  • Multiple steps flow where you might have session lengths. But avoid limiting form sessions length if you can.

Documenting Wayfinding

Wayfinding is the documentation of things that will help people find their ways on the page (navigation and more)

HTML title of the page

The examples until now were mostly documentation at component level. There are more things you can document at page level.

Starting with the HTML title of the page for example.A screenshot of a Jira page with a title table in 3 columns: HTML page title and HTML title example for different contract and operation pages of a projectIt is displayed in browser tabs. It is also announced by screen readers. This helps users know where there are and what they can expect to find on that page. For those, we use a Jira ticket (because we don’t have confluence ^^). You could also document this in mockups .

Skip Links

Designers can also document the Skip Links. Those are links that let screenreader users skip directly to the main content of the page. And sometimes to the search. They are often “invisible” by default but are visible on focus (and announced by screen readers). You can also keep them visible all the time in the header. Up to you.Example of a Skip to Content link on a cooking site that shows the link is going to the main content area of the pageYou can document

  • Where the link is
  • What is looks like when focused (if invisible by default)
  • Where it will send users.

Landmarks

The skip to content was sending the user to an area of my document that is called “main”. But there are more areas that help screen reader users orientation on the page: the Aria Landmarks. This is really useful for screen reader users, because it lets them get a sense of how the page is structured.

A page with the different aria landmarks marked with little boxes (navigation, banner, main, etc.)

This is an example of the ARIA landmarks website, documenting landmarks areas with colored annotations. Inception anyone?

Those can be documented as well, maybe with the help of developers or accessibility experts.

HTML headings in the page

Proper HTML headings is another important aspect of accessibility: H1, H2, etc. I can do 2 things:

  • I can use heading level as annotations on the mockups
  • I also name my styles with the proper heading level so that others designers can re-use them.
In this example I documented a H1 for the title of the recipe, then H2 for Ingredients and Preparation Steps, etc.

In this example I documented a H1 for the title of the recipe, then H2 for Ingredients and Preparation Steps, etc.

This is the sort of thing that you could also document with content people.  Sometimes you need a heading level but this would mess up SEO. For those cases, you can use the aria-levels (and a p tag). Check with your devs. If you want an example, check the code of my “let’s get in touch” footer. The title is visually the same as H2, but this makes no sense for SEO. So it got a role=”heading” and “aria-level=2” instead.

Focus order at page level

Some people will navigate a site without a mouse, using the tabulation key. The focus order should follow the logic of the flow of the page.A complex website with annotations to show the focus order at page levelThis example is from a Figma template by the Fluent Design System team of Microsoft. They provide a Figma kit to help you with such annotations.

The mockup is in the background. On top of it, you have small annotations. With the corresponding documentation of their focus order on the right. In this case, after the user navigates through the top navigation and first “site header”, they enter the main content. They start with the left sidebar, then a “return” link; and finally to the right part of the content.

Focus order in form elements

Sometimes, you might document the focus order at component level. This often happens if the components are in a multi columns layout.2 examples of how to document focus oder for a 2 column formIn my example here, I have a 2 columns form. And I documented how the user should go through left column first:

  • Who are you
  • What is your request about
  • Your email address

Then the users goes on the right side:

  • Your message
  • Submit

I document this with little annotation numbers on the form fields. And arrows to show the order (which is my example on the left)

If you are using Figma, the team at Microsoft created a plugin: A11y Focus order, that will help you with that. This is the example on the right. You can select the elements then give them a number in the plugin. And you can reorder them as well.

Documenting Announced Content and Markup

Image alternatives and assistive technologies (screen reader) announcements

If there are images or icons in the mockups, designers can document what the assistive technology should announce.

In my example on the left, I have a cooking recipe site with an image of a slice of pizza at the top

What shoudl the assistive technology announce for those images?

Examples of documentation for a pizza header page. The pizza has a alt text while the icons don’t

I use the annotation technique to document the alternative text for this image:

  • A number on the image
  • The alternative detailed documentation on the right

I also have 3 buttons: save, share, rate. Each has an icon and a label

In my annotations, I explain that the screen reader should NOT announce anything for the icons.  Otherwise it would be annoying to have twice the same information.

I am not sure here how the developers will implement the icons. So I prefer not to document exactly if this should be an empty alt, a role=presentation, … I could also discuss with them. Then update the documentation to reflect how this would be implemented.

Is this content going to be generated by a CMS/WYSIWYG?

An example of the image details for alternative text and captions in WordPress

One small detail: here I assumed I am the one coding the pages. But this is a cooking recipe page. There is a good chance this content is going to be generated by a user, using some sort of CMS (or WYSIWYG)

Which means: you need to develop the alt text field as well. If you are interested in the topic, take a look at the ATAG: Authoring Tool Accessibility GuidelinesAnnounced text for "icons buttons" In this second example on the right, my icon buttons do not have visible labels. So I need a screen reader to announce those.

I again use the annotation to document that:

  • the first is “view graph”
  • and the second “view table”

With the help of my dev team I could bring this one step further. They can add documentation for some ARIA states (selected, etc).

Announced content order

I can also document the announced content order. This is interesting when the order might be different from the HTML flow. Please note that most of the time you want the same announced and visual order. So, be careful with this.

Announced (HTML) content order vs Visual order (be careful with this one)

An example of vertical thumbnail of a cooking recipe with annotations on the right to show announced content order

In this example, I have a small version of a cooking recipe “thumbnail” component. This component will be used in a grid page (aka there will be a lot of those on the same page). It has a vertical layout, image at the top with a save button on top of it. Then categories, recipe title and summary.

  • I don’t want the image to be announced, because there will be a lot of those and it might get annoying.
  • The H1 title should be announced 1st. This is why it’s in a big bold font in my design. It conveys visually the hierarchy. So this gets number 1.
  • For the save button, even if visually at the top (mostly to gain space), should be at the bottom of the HTML and announced last.

How would you implement this then? Marie Guillaumet, accessibility expert at Access42, explained to me:

“Even if the title visually appears after the categories, in the HTML code, you need to put it before. This way the screen reader will read the title, then the categories. Then you use CSS to invert the order visually in the component”.

If you want to dig further in the topic of screen reader I recommend:

Ambiguous Links

Sometimes the “clickable” part of an element might not be obvious. Especially when they wrap a whole component.A tile with 5 list items for different content. Annotations show that each is a link to a contentIn this example, we have a tile with 5 list items. Each has an icon, a title, a number and an arrow. Dev teams might ask “where should I put the link, is it on the title or the whole element???”

I can document this directly with annotations as well. Or I can put that info in a Jira ticket.

Extra content for assistive technologies

Sometimes, screen reader users need some extra information.Documentation for the assistive technology content for the 2 tasks and documents buttons and what the screen reader should announce when there are notificationsIn this example, if I have a notification badge with a number of items. Just announcing the number might be confusing. I can document how this should be announced for different scenarios:

  • No new documents in my documents (if there is no notification)
  • 5 new documents in my documents (in case I have 5)
  • No new tasks in my tasks
  • 5 new tasks in my tasks (in case I have 5)

More form accessibility documentation that experts can help with

There are more things you can document for form accessibility. But this might require a little bit more help from experts / devs. But, for many of the examples, you could collaborate with developers and accessibility experts to add even extra information to that documentation such as:

  • Correct HTML semantic elements (are we using buttons or href links)
  • ARIA Roles
  • ARIA states and propertiesForm documentation accesssibility experts can help with. With some examples of fields documented in the design systemFor forms for example, we could add:
  • What is the Correct HTML5 type? In my example here, this is documented with a little pink annotation next to the right field: option, type=date, type=search.
  • Is this field supposed to have autocomplete, autofill, etc. (attributes)
  • Legends and field grouping markup
  • Default focused elements when page opens (if needed, often it is NOT needed

Access to external documentation for captions, transcripts, etc.

Finally, there are things you can’t document in design files. For those, I often provide links to external sources.

Such examples are

  • Caption for videos. You can provide a link to the plain text transcript and / or a link to the .srt file
  • HTML/text resources for Audio transcripts (for podcasts for example)
  • A list of links/CTAs with the anchors. “Click here” links are horrible for accessibility AND for usability. You want to avoid that. Often content people (SEO, UX writers) will provide a whole list of such links with the actual URL, the anchor, the title, etc.

Who should document accessibility?

I presented how and what to document. The last question to answer then is: who should document all of this? I have two answers for you:

  • It’s a team effort!
  • It depends…

It’s a team effort

Product / Project Management, Design teams,Devs / Accessibility experts, Content- UX writers / SEO, QA/ TestingAccessibility documentation is a team effort. A lot of people can participate in such documentation:

  • Product and Project Managers can define and document accessibility requirements at project level. Do we target AA or AAA for example? Also, they can make accessibility part of the Definition of Done if you work in an agile environment.
  • Designers design and also document how it works and what it looks like. They also document navigation, the “hidden” interactions and what assistive technologies should announce.
  • Developers & Accessibility experts document the technical implementation. Things like correct markup, ARIA roles, landmarks, …
  • Content people, UX writers and SEOs can help document alternative texts, call to actions and link anchors that make sense for users, and more generally everything content related.
  • Testers and QA (quality assurance) teams define and document accessibility test cases: how are we going to test this?

It depends (on what people are comfortable with)

A 3 sections matrice explaining what I can document on my own, with the help of devs/accessibility experts and content peopleWhen it comes to who should document, my advice is: Start with what you, your team are comfortable with. Then build upon this base!

While preparing this talk, I tried to organise what I can document on my own, what I need the help of devs / accessibility experts with. And what I would like the help of writers and SEO with. I put all the types of documentation I just showed you in this 3 section matrix.

This is a very “personal” way of ordering things. It is based on my own areas of expertise.

I advise you to do something similar with your team. Of course, your mapping will be different. It depends on a lot of factors, including level of accessibility expertise for designers and dev team. The type of project might also change this. A single page app will not have the same needs and levels of page/component as a blog for example.

It is an interesting exercise to do with the team to see how confident and comfortable people are documenting things.

When do you document this?

Finally, one question I get a lot is “when do I document all of this”

I document final & tested components / pages, after discussion with devs about technical feasibility. Which means I might rework some mockups based on technical feasibility. And then create the final documentation.

It takes a little bit of time to document. But it also helps have a good base for communication with the dev team. So, on the scale of the project, it actually helps gain time.

What are the benefits of such documentation?

I gave you plenty of examples of what to document. The final question now is: what are the benefits of such documentation?

Why should we do it and how do I convince my team to invest time in design documentation for accessibility? Well, a few reasons…

It benefits myself, as designer

The first benefit of documenting accessibility is for myself, as a designer. It helps me learn more about accessibility. To document such things, I had to learn about it.. So documenting helps me keep up to date and understand more accessibility needs and requirements.

It forces me to think about different interactions, beyond the “static” pixels I am working on. Documenting is a nice mental effort that forces me to take a step back and ask myself:

  • How will someone interact with this with a mouse?
  • A keyboard?
  • How will it work on touch?
  • What will a screen reader announce for that? Etc.

Sometimes, I am too deep into the pixel details of something.  I don’t notice that this will not work, once people interact with it.

This helps me see that, and rethink a whole new solution if needed.

It benefits the designer- developer relationship

Design documentation helps avoid some misinterpretations. Of course this doesn’t mean that you don’t need to talk to your devs, or don’t need to present your mockups. Sometimes there are months between the moment I designed and presented something to the dev team and the moment that Jira ticket arrives in their backlog. Having a solid base of documentation helps remember and restart the conversation.

It also helps bring consistency to future pages and interactions. If interactions and accessibility are documented for one component, then similar components should work the same way. And trust me, my developers hold me accountable. Sometimes they will come and ask me “Stef, this is almost the same thing, why is this working differently?” And they are right to ask.

Companies, stakeholders, PMs might think such documentation is a waste of time. But, what happens if the designer doesn’t document how it works, states and all? Well, the developers will have to come up with that.  Which means, you don’t gain time or money at the end of the day by not documenting. You just shift the costs from design to development. And I think you might even lose money then. Developers will often need more time than designers figure the missing peaces out.

It benefits current and future fellow designers

It’s a good onboarding tool for new members, especially if they don’t know about accessibility. They get examples of what is expected from them. Often, they will ask a lot of questions. And will learn about accessibility from that kind of documentation as well.

Prior documentation also helps set standards as to what is expected for the next designs. This again helps bring consistency when the design team grows.

It benefits everyone else in the team

Such documentation helps start conversations about accessibility within the company. It encourages them to dig further and learn about that topic as well. And helps make sure accessibility is NOT an afterthought anymore!

In conclusion…

I share with  you a lot of things you can document as a designer to help push accessibility forward.

The goal was to give you some examples. But I will be honest, I don’t always have the time to document all of that in design mockups. I would say: pick your battles. If time is limited, document the things where there might be the biggest issues and misunderstandings

The important thing is teamwork.  Even if you don’t document everything, communication is the most important aspect here. With the other designers, with the dev team, with the testers. So that we can push accessibility forward together for everyone. And make it part of the projects from the start.

And yes, it is a BIG, long, demanding job.

Get my Sketch Annotation Template +  Accessibility & Interactions Documentation Checklist

Wow. That was a lot. But don’t worry, if you don’t remember everything that you could document, I prepared a checklist for you. Also, a few of you asked me if they can get my Sketch file for those symbols, so, I will send this to you as well!the sketch symbols template + a pages of a checklist in a google document

Subscribe to my newsletter to download the resources

Sign up for my Newsletter* below to receive the accessibility and interaction documentation checklist and the .sketch annotation template file.

You will get a first email, asking you to confirm your subscription. Once you confirmed your subscription, the .PDF template will be then sent automatically to the same mailbox you used for the subscription. Gmail sometimes puts those emails in spam, so check your spambox in case you didn’t get anything.

*The Newsletter is sent when there is a new article on the blog. It’s a good way to not miss any articles or new resources. And to get notified when my weekly summary of curated UX, design and tech content Pixel of the Weeks is published! You can unsubscribe anytime you want.

(all fields are mandatory)

Thanks, resources and links

First, many thanks to Alain Vagner, Marie Guillaumet, Geoffrey Crofte and Myriam Jessier for the help and feedback with that talk, Goulven Baron and Karen Hawkins for letting me user their work.

The Slides

You can get the full version of the slides here. Please remember that all rights are reserved on the slides. Feel free to share them, but if you want to use any image, please contact me before.

Links in the slides

More links to help you build and document better accessible designs: