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. You can also get access to my checklist and Sketch Template at the end of the article to help you remember all of this. Or check the video replay of the talk and the sketchnotes. I also prepared a Accessibility & Interactions Documentation Kit to help you get started.

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 in September 2022 , for Web Accessibility in Mind conference and Inclusive Design 24 to reflect the structure and content of a new version of the talk.

** Une version français de l’article et la conférence sont disponibles ici **

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

A 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 project. 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“.I 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:

Jira tickets used as documentation / research repository
Confluence pages (or whatever knowledge base tool you use)
Separate documentation in a word doc, excel sheet
Miro board (mockups + docs)
Figma comments

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 Alternative 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 Color accessibility: tools and resources to help you design inclusive products and Tips to Create an Accessible and Contrasted Color Palette.Here 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.Here 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 a text for a darker grey. I can then put this matrix in the project, to let other designers know the color combinations they can and should not use.

It might be interesting to share this matrix with the whole design team (or development team) somewhere in the system design to help them understand the possible associations.

Documenting specific color combinations in the styleguide

In the design system, I also try to document the use of certain color combinations: what is allowed and not allowed.

I have an example with statuses in my design system. Each status has 4 variant.
For success, I have 4 shades of greens: dark, main, light et contrastText. (Names come from material UI, don’t ask)

I documented how colors can be combined (and can’t) be combined for our statuses all across the interface. For example: I can use contrastText (or white) as text color on top of the dark variant for success status.

Educate design teams on AA, AAA, and contrast ratios.

Not all designers might be familiar with the ratios, AA / AAA meaning and small vs big text concepts. 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. In my example I document different button states:

default,
hover,
focus,
active,
disabled.

The focus state is very important for accessibility. It helps keyboard users know where they are when navigating on the page. You could also have extra “non” HTML official states like “loading”. For checkboxes I have:

default,
focus,
checked,
disabled,
disabled checked,
indeterminate,
disabled indeterminate.

The last two are not in the HTML specification. But we sometimes need them on tables where the user can check several rows. Same for radio buttons, except they are not indeterminate.

For form inputs, at the 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.In 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

Designing for Keyboard Accessibility
The difference between keyboard and screen reader navigation
browsing with a keyboard
A table to help you with keyboard testing (but also shows you the main expect implementations)

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

Ambiguous Links

Sometimes the “clickable” part of an element might not be obvious. Especially when they wrap a whole component.In 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.

Also, when working with links, make sure that the text of the link, aka the anchor is explicit. You want to avoid “click here” links and have more explicit links to help people understand what will happen when they click.

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.If 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

I suggest “Foundations: pointer gestures” for more details as to what is a complex gesture or not and how to deal with those.

Zoom behavior

For complex responsive pages, you could also document the “zoom” behavior. Users should be able to zoom the site up to 400%, without it breaking the content (no hidden text, images, etc.)

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

But I think this can be really useful for native apps.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.On 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”.User 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.It 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.You can document

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

HTML5 sectioning elements and ARIA 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 landmarks can be documented as well, maybe with the help of developers or accessibility experts.

Please note that several HTML sectioning elements automatically create ARIA landmark regions. So, if you use HTML5 elements like main, header, nav, etc, you don’t need to double down with an ARIA role. More information on the ARIA Ladmark Regions page.

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.

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.This 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.

This type of documentation might be overkill for simple pages. But if you start working in complex B2B apps (like Sharepoint, haha), with a lot of interactions, it can become quite handy.

Focus order at component level: in forms

Sometimes, you might document the focus order at the component level. This often happens if the components are in a multi-columns layout.

Here is another example of such documentation at the component level for a complex modal with many checkboxes. I document the tabbing (focus) order throughout the modal content with numeric annotations:

The text field
The checkboxes in a certain order
The cancel button, then confirmation
The closing of the modal.

I also specify that the modal must be closeable using the escape key.

I can 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 and then give them a number in the plugin. And you can re-order them as well.

Documenting Alternative 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 GuidelinesIn 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:

A 4-step process for testing the accessibility of your designs

Extra content for assistive technologies

Sometimes, screen reader users need some extra information.In 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)

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

Accessibility 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)

When 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.

Accessibility & Interactions Documentation Kit

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. And some Sketch and Figma Annotation kit, to streamline your design process and save you time. You can now get it on my brand new shop.

Get the Checklist and Annotation kit

Videos of the talk

The talk was live on YouTube as part of the Inclusive Design 24 conference. You can also get the Webaim replay.

Sketchnotes

At Clarity 2022, two awesome people drew some Sketchnotes of my talk

Sketchnote drawn by Jina Anne

Sketchnote by Raquel Breternitz

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.

Links in the slides

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

Include – Accessibility Annotations: a useful Figma plugin to help you annotate landmarks, focus groups (native), headings, reading order, alternative text (for images, it’s missing icons for now), check touch target, color contrast, create de 200% version of your page, document complex gestures (native) and more.
Color accessibility: tools and resources to help you design inclusive products
Accessibility annotation Figma template (by twitter)
Inclusive Components
browsing with a desktop screen reader
browsing with a mobile screen reader
browsing with a keyboard
browsing with speech recognition
How to document the screen reader user experience
Designing for Web Accessibility in 60 Seconds
Text Resizer – Accessibility Checker
Firefox Accessibility Inspector

A Designer’s Guide to Documenting Accessibility & User Interactions