Accessibility annotations in handoff: what to write for developers

Accessibility annotations tell developers how a design should behave with a keyboard and screen reader: alt text, headings, focus order, and accessible names.

info Quick Definition

Accessibility annotations are notes that accompany a design in handoff and describe what cannot be seen on screen: alt text, heading levels, landmarks, focus order, accessible names, and keyboard and screen reader behavior. They let developers implement accessibility without guessing.

What are these annotations?

A design is a still image. A screen reader and a keyboard do not see the image; they read a structure. Annotations describe that structure in the design layer, because it is often absent from the mockup. TestParty, an accessibility software vendor, puts it plainly: the visual layout does not dictate focus order, and that has to be stated.

They are useful in any handoff flow, with or without a specific tool. What matters is that the information travels with the design. Microsoft Learn, for example, teaches how to do it in Figma with plugins that draw numbered focus order indicators, and with name, role, and state tables.

What should a designer annotate?

The list depends on the screen, but these are the most common annotations:

Annotation	What it specifies	Example
Alt text	What the image conveys, or that it is decorative	“Bar chart: sales by quarter” or “decorative”
Headings	The hierarchy level of each title	“H1: My orders”, “H2: Pending orders”
Landmarks	The main regions of the page	Navigation, main content, search
Accessible name	What a screen reader announces	A close icon is named “Close dialog”
States	Only the ones that matter in the flow	A disabled button, a field with an error
Focus order	The Tab sequence on complex screens	From the search field to filters, then to results
Keyboard behavior	What Enter, Space, or Escape do	Enter and Space activate a button
Dynamic announcements	Changes announced without moving focus	“12 results found”

Some rules from Microsoft Learn:

Headings: there can be only one H1 per page, and levels cannot be skipped (you do not jump from H2 to H4 without an H3).
Landmarks: most of the time headings are enough; define landmarks only on long pages or pages with clear regions, and fewer is better. There can be only one banner.
Repeated names: if two buttons are both called “Create”, a screen reader announces “Create, Create” when navigating by buttons. Annotate an accessible name that includes the visible one, such as “Create welcome template”.
States: annotate them when they illustrate a key condition in the flow, such as a disabled button.
Alerts and error messages: they must reach the screen reader without stealing focus.

Alt text has a practical rule: if an image is decorative, mark it as such. In HTML, the W3C says to use an empty alt attribute (alt="") so assistive technologies ignore it. Do not omit the attribute, because some screen readers may announce the file name. In the annotation, writing “decorative” is enough.

What is the difference between focus order and reading order?

Focus order is the sequence in which interactive elements receive focus when navigated with Tab. Reading order is the sequence a screen reader follows as it moves through the content. They often match, but they do not have to.

WCAG 2.2 requires, in criterion 2.4.3 (level A), that focusable components receive focus in an order that preserves meaning and operability. According to the W3C, focus does not need to follow the visual layout, but it must respect the relationships the design implies. Criterion 1.3.2 (level A) asks for something similar for reading sequence: it must be programmatically determinable when it affects meaning. Without scripting or tabindex, focus follows the order of the code, so if the code does not match the design, the designer has to say so.

Microsoft Learn recommends showing the sequence with numbered indicators in the design. Numbering is most useful when the logical order does not match the visual layout, for example a card whose action button sits to the left of its title.

How do you annotate focus in a dialog?

Dialogs and menus are where focus most often breaks. Microsoft Learn states that when a dialog or menu opens or closes, focus should land back on the component that triggered it. TestParty notes that focus behavior for modals is rarely specified in designs and asks teams to document where focus goes when they open.

Also note what Escape does when it closes a dialog, and what happens when a user reaches the end of a list of options.

How do you work with developers?

Annotations are not written once and forgotten. A workflow that works:

Annotate before reviewing with developers, so you have a concrete proposal.
Walk through the flow with the keyboard only, together with the person implementing it.
Test with a screen reader before you finalize names and roles.
Keep the annotations in the same design file or system, not in a separate document nobody opens.

If your team already has a design system, documenting components with their states and behaviors reduces the number of annotations per screen.

When should you NOT annotate everything?

Digitala11y warns that annotating everything is rarely effective: excess documentation overwhelms developers and buries the essentials. Its goal, it says, is to guide intent and priorities, not replace testing. Prioritize:

Complex components: menus, tabs, accordions, dialogs, and pickers.
Forms: visible labels, instructions, and associated error messages.
Screens where visual order and logical order differ.
Content that changes without a page reload, such as alerts or search results.

The rest usually inherits the behavior of components that are already documented.

Example

Illustrative example: a team designs a filter screen for a product catalog. The mockup shows filters on the left and results on the right. Without annotations, developers build the focus order as it appears in the code, which reaches the results before the filters. The designer adds a note with numbered focus order: filters first, then results, and a note that the result count is announced when it changes. The implementation matches both the screen and the keyboard.

Common mistakes

Leaving alt text for the end, so it ends up as “image” or the file name.
Confusing heading level with text size: an H2 can look large or small.
Annotating focus order without testing it with a keyboard.
Forgetting focus when dialogs close, which leaves keyboard users lost.
Using repeated generic names such as “Create” or “Submit” with no context for someone navigating by buttons only.
Thinking an annotation replaces testing with people who use screen readers.

To validate what you annotated, screen reader testing is the natural next step. If you want to understand the accessibility tree the browser builds from your design, the accessibility tree explains it. And for the non-technical side, cognitive accessibility adds criteria about memory and attention to these notes.

Sources

Frequently asked questions

What are accessibility annotations?

They are notes attached to a design, or kept in a handoff tool, that describe things you cannot see on screen: alt text, heading levels, focus order, accessible names, and keyboard behavior.

What should a designer include in the handoff for accessibility?

At minimum: alt text for images or a note that they are decorative, heading levels, landmarks, accessible names for icons and controls, the states that matter, and focus order on complex screens.

What is the difference between focus order and reading order?

Focus order is the sequence in which elements receive focus with the keyboard. Reading order is the sequence a screen reader follows. WCAG requires both to preserve meaning and operability (criteria 2.4.3 and 1.3.2), but not to follow the visual layout.

Do you need to annotate everything?

No. Digitala11y warns that annotating everything is rarely effective. Prioritize complex components, dialogs, forms, and screens where the visual order is not obvious.