Accessibility annotation

A mockup is a picture of a rendered result, and a good half of accessibility is not in the picture. Nothing in a comp says whether that bold line is a level two heading or a styled paragraph, what the icon button is called, which of the six controls is reached first, whether the count that updates is a live region, or what the photograph should say when it cannot be seen. Those decisions exist whether or not anyone writes them down. Annotation is the practice of writing them down, in the file, next to the thing they describe.

The alternative is not that the decisions get skipped. It is that they get made silently, at implementation time, by whoever is closest to the markup and furthest from the intent, usually in whatever order the elements happened to be built in. That is where an accessible name becomes “button”, where focus order follows the DOM instead of the task, and where a heading hierarchy turns into a set of font sizes. None of it shows up in a visual review, because visually the build matches the comp exactly.

What is worth annotating is short and fairly fixed: heading levels and the document outline, focus order and any initial focus, roles and accessible names for anything whose label is an icon, alt text for images and the ones that are decorative, live regions and their politeness, keyboard behaviour for custom widgets, and what happens at reflow when the layout changes. Published kits exist for all of it. Primer’s annotation toolkit and the Microsoft accessible design toolkit both ship stamps for exactly these categories, which matters mostly because a shared vocabulary stops every designer inventing their own notation.

Two failure modes are common enough to name. The first is annotating everything, which produces a file nobody reads: annotate what the picture cannot say, not what it already says. The second is annotating once, at handoff, and never again, so the notes describe a design two revisions old and the developer learns to ignore them. The healthier version treats annotations like any other spec detail, kept beside the component in the design system so most screens inherit their semantics and only the genuinely new parts need a note. A design system that documents the accessible behaviour of its own components is the reason most screens need no annotation at all.