Sure, most of us have an understanding of markup and styles and the things that can affect an app or a site’s performance. But many designers rarely think about HTML code and content from a semantic (containing meaning rather than only appearance) perspective or how keyboard and non-sighted users experience web pages. This should change.
As designers, we can step up our game by creating accessibility annotations – simple callouts that communicate intended content structure, tab stop order, and screen reader notes – in our mockups. Doing so helps us serve all of our users by providing a blueprint for accessible, inclusive experiences.
What are accessibility annotations?
Deque, the same company behind the axe testing tool, offers a downloadable accessibility annotations toolkit with files for Adobe Illustrator and Sketch as well as individual SVGs. The library contains symbols that call out headings, tab stop order, and screen reader notes, among other things. A designer can place the symbols into their mockups just as they would add annotations that detail interaction design behaviors in the UI. The accessibility annotations communicate the intended experience for keyboard and screen reader users. Doing so helps eliminate ambiguity – developers can code a page according to a designer’s notes, just as they would when implementing the visual design.
How we use accessibility annotations at Ad Hoc
Too often, accessibility can be a last-minute consideration, when ideally it should be baked into a team’s design and development processes. Taking cues from the Accessibility Beyond Compliance Playbook, designers at Ad Hoc use annotations to help socialize accessibility best practices and inclusive processes throughout the external teams we consult. Bubbling up “unseen” behaviors and interactions through the annotations has the dual effect of guiding development and putting accessible, inclusive design on the radar.
For teams that already have accessibility reviews incorporated into their cycle, the annotations speed up the QA and design review process. Accessibility specialists no longer need to guess what a designer’s intent is – they can follow the annotations to get a sense of the keyboard and screen reader user experience before any code has been created.
One of Ad Hoc’s teams began instituting accessibility annotations on a consistent basis in late 2022. This was part of a larger initiative to create a formal process where designers meet with an accessibility specialist to talk about their design intent, review the visual mockups together, and discuss the user experience for keyboard-only, low vision, or non-sighted users. The goals of this review are to:
- Reduce developers’ guesswork and assumptions by providing guidance for semantic HTML and UI interactions. By doing this, we reduce bugs being introduced in production.
- Push designers to think about accessibility earlier in their designs — accessibility considerations are incorporated holistically rather than as an afterthought.
- Provide an educational opportunity for product managers, designers, and developers by helping them better understand semantic HTML and the experience of a broad range of users.
On another contract, we use accessibility annotations to make the most of design review meetings. In these meetings, designers get the opportunity to discuss their intended user experience and visual mockups with an accessibility specialist before high-fidelity prototypes are made or any code has been created. Doing so supports Ad Hoc’s accessibility-first philosophy.
Getting started with accessibility annotations
When designing, it’s important to consider the needs of all users, including those with disabilities. To ensure that a design is accessible and usable for everyone, consider adding annotations with notes or instructions specifically for people who rely on assistive technologies like screen readers.
This is helpful because:
- It gets you, the designer, to think about the user experience of those who use assistive tech, a mouse instead of a keyboard, etc.
- Documenting these requirements also provides clarity for engineers and stakeholders so that there isn’t any guessing of intention on their part.
When one of our teams meets for a Design Accessibility Review, our annotations actually begin in text format within a document such as a Jira ticket or Google doc. A great example that we use as a reference is this accordion pattern documentation from W3C. While we discuss the visual and interaction designs, we list out our mapping of things like:
- Semantic headings in the design
- Page titles (especially considering state and content changes)
- Accessible names/labels of UI elements
- Focus (tab) order of interactive elements
Below is the template we use in the Jira ticket to facilitate design accessibility review discussions while reviewing the visual mockups. You can copy, paste, and then edit this template in the “Description” section of your own Jira Design Accessibility Review ticket.
# Name of the item to be reviewed:
What is the name of the thing you're building?
## Briefly describe the purpose or goal of this feature/interaction:\*\*
Your brief description here.
## Accessibility Annotations
Feel free to lay this out here or we can discuss it together.
### Headings
This declaration of headings is meant to define the [semantics of the element](https://primer.style/design/accessibility/semantic-html) and not the classes and visual styling of the headings. (If you don't understand the purpose of headings and html structure then it may be useful to [read this helpful article on heading structure](https://webaim.org/techniques/semanticstructure/#headings).)
Note:If alerts will be displayed after a user's event, those should be taken into account for the html heading structure as well.
Example heading structure:
**H1** - My Favorite Recipes
**H2** - Quick and Easy Recipes
**H3** - Spaghetti
**H3** - Tacos
**H4** - Fish Tacos
**H4** - Black Bean Tacos
List headings here:
### Page Title(s)
[See this resource from 18F](https://accessibility.18f.gov/page-titles/). As a user goes from page to page or if significant content changes occur on a page, we need to define the page titles.
- Define page titles. Loop in the Content Team for this.
- List out page titles here or link to another doc that contains them. The A11y Specialist will use this info in QA.
### Focus order
Add mockups or list here what you think [the focus order](https://devyarns.com/logical-focus-order/) should be.
### Accessible names/labels
Define any [accessible names ](https://govtnz.github.io/web-a11y-guidance/ka/fundamental-concepts-in-web-a11y/accessible-names-and-descriptions/accessible-names.html#what-s-an-accessible-name)of elements here, if needed.
---
## Designer's Checklist
Some other points to think about ahead of time. Check off ahead (if useful) when you've considered them. Feel free to use this as starting points for documenting the experience above.
- Do I need to define a [page title](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title)?
- Do you need alt text for images (including icons)?
- Do you have mobile/responsive considerations?
- Have you considered focus management and focus order? We should document for the devs what the tabbing order would be for a keyboard-only user? Defining your expectations for this can be helpful for the devs when they build the structure of the elements.
- You should have an opinion on heading hierarchy (h1-h6)—not font-sizing, but actual hierarchy.
- Have I checked [color contrast](https://webaim.org/resources/contrastchecker/)for at least 2.1 AA acceptable rating?
- Should I document screenreader text or alt text for developers to use?
- Would extra screenreader-only text be helpful for users? Don’t overdo this—and simply create noise for the user—but consider the non-visual user as well.
- Will [aria-labels](https://developers.google.com/web/fundamentals/accessibility/semantics-aria/aria-labels-and-relationships) be used? What should that text say?
- What if there are slow (network/cellular/wifi) connections for the user?
Template created by Ad Hoc designers David Kennedy and Dan Bivins.
After this review is completed, the designer can then move the text-based annotations to a visual format in Sketch or even just hand off the text-based version, depending on what is best for the team and situation.
In one scenario with a different customer, our designers start off by adding an annotations library from a shared Sketch for Teams workspace. The library contains visual annotations that convey the expected semantic structure, keyboard navigation order, and screen reader UX for keyboard and screen reader users. Using the Insert/Symbols menu in the Sketch desktop app, a designer can easily navigate to the accessibility tag they need and insert it into their mockup.
HTML annotations
HTML annotations are notes or comments that are added to HTML code to provide additional context or explanations. To improve the design hand-off process, use the call outs sparingly to communicate design decisions or requirements to developers, or to provide instructions for how certain elements should be implemented.
Repeated UI elements, such as navigation, that behave the same way between screens may be tagged once or not at all, depending on your use case. It’s always a good idea to collaborate closely with the developers and accessibility specialists early in your process. Ask what kind of tags will help them to implement or review your work.
Focus order of interactive elements
Ensure the correct implementation and accurate reflection of the original design intent by calling out the focus order. Interactive elements, like buttons, links, and form fields, must have a logical and intuitive focus order to improve web page usability. This also improves overall accessibility and usability for all users.
Screen reader notes
It’s important to ensure that design notes for screen readers are clear, concise, and easy to understand, as screen readers will read them aloud to users who rely on them. Be mindful of the limitations of screen readers and consider how users who rely on them will experience the design.
Design notes can include information about the purpose and behavior of elements, instructions for how certain elements should be implemented, or explanations of complex interactions or layout changes.
Using annotations to improve everyone’s experience
Accessibility annotations belong in every designer’s toolkit. They offer a way to socialize best practices and surface the experience of screen reader and keyboard users in a way that easily integrates with the design process. With accessibility annotations, it’s now easier than ever for each of us to become an accessibility champion.
