skip to content

In a design handoff, which accessibility annotations should a designer add, and why can't engineers infer them from the visuals?

level: middleimportance: should knowfreq 45%

answer

  1. looks like versus is
  2. visual order is not reading order
  3. big text is not a heading
  4. an icon has no words
  5. twenty identical Stop buttons

basics

~20 s

Annotate focus order where layout is ambiguous, heading levels, labelled landmark regions, accessible names for icon-only and repeated controls, and where focus goes after actions. Layout, type size and icon shape do not encode that intent.

solid answer

~40 s

The visuals show *what it looks like*; assistive technology needs *what it is*. So the designer annotates **focus order** wherever the layout can be read more than one way — a detail panel beside a table; **heading levels**, because a large label is not necessarily a heading and a small one may be; **landmark regions** with labels, unique when a region type repeats; **accessible names** for icon-only buttons, by function (*Refresh*, not *circular arrow*), and for repeated row actions (*Stop instance web-01*, not twenty identical *Stop*s); and **focus destinations** after actions, such as when the focused row is deleted. These support WCAG criteria including 2.4.3 Focus Order, 1.3.1 Info and Relationships and 4.1.2 Name, Role, Value — all Level A. None of it is visible in pixels, so unannotated it gets guessed or skipped.

go deeper

for a junior

Recall the core annotation set — focus order, headings, landmarks, accessible names, focus destinations — and one reason each cannot be read off a mockup.

for a middle

Explain the naming guidance — function over form, distinguishing words first, concise, no role word — and why a repeated row action needs a unique name that still contains its visible label.

for a senior

Show how you would make annotation routine across teams: an annotation kit in the design library, a review with engineering before build, and annotating only where order or meaning is genuinely ambiguous.

for a principal

Weigh who owns accessibility intent — design, engineering or a specialist — and how a system's components and annotation kit shift work from every screen to the shared layer.

## Why accessibility intent is invisible in a mockup A mockup encodes appearance. A screen reader, a keyboard, a switch device or voice control needs **structure and meaning**: what each thing *is*, what it is *called*, and in what *order* it is met. Some of that structure an engineer can read off the design — a text field with a visible label has an obvious name. Much of it only the designer knows: - Two columns side by side can be read left-then-right or top-then-bottom; the design does not say which the designer meant. - A large, bold line of text might be a heading, a key figure or just emphasis. - An icon's meaning lives in the designer's head: the same arrow could mean refresh, retry or sync. - A button labelled *Stop* on every row is clear to a sighted user, who sees which row it sits on, and ambiguous to anyone who hears the buttons as a list. **Accessibility annotations** make that intent explicit so the implementation can expose it. The rules themselves come from WCAG and the WAI-ARIA Authoring Practices; the annotation's job is to record the designer's decisions against them. ## The annotation set | Annotation | What it records | Why the visual cannot tell | Related WCAG 2.2 criterion | |---|---|---|---| | Focus order | Sequence of interactive elements | Multi-column and floating layouts are ambiguous | 2.4.3 Focus Order (A) | | Reading order | Sequence content is announced in | Visual grouping is not sequence | 1.3.2 Meaningful Sequence (A) | | Headings | Which text is a heading, and its level | Size shows emphasis, not structure | 1.3.1 Info and Relationships (A); 2.4.6 Headings and Labels (AA) | | Landmarks | Region type and label | Whitespace and borders are not structure | 1.3.1 (A); one way to meet 2.4.1 Bypass Blocks (A) | | Accessible names | Text for icon-only and repeated controls | Icons and context carry no words | 4.1.2 Name, Role, Value (A); 1.1.1 Non-text Content (A) | | Focus destination | Where focus lands after open, close or delete | A static frame shows no sequence | 2.4.3 Focus Order (A) | ## Writing accessible names that work The WAI-ARIA Authoring Practices give plain guidance that belongs in every annotation kit: - **Function, not form.** An icon that looks like an X and closes a panel is named *Close*, not *X*. - **Distinguishing words first**, usually a verb for actions: *Stop instance web-01* rather than *web-01 stop*. - **Concise** — one to three words is often enough. - **No role word in the name.** Do not call a button *Refresh button*; the role is announced separately, so the word is heard twice. One more rule connects names back to the visuals: under **2.5.3 Label in Name** (Level A), when a control has a visible text label, its accessible name must contain that text. So the row action keeps the visible label *Stop* and gets the name *Stop instance web-01* — a speech-input user who says *Stop* still reaches it, and a screen reader user hears which row it acts on. ## A worked example: an instance detail view A cloud console shows an instance table with a detail panel that opens on the right. The annotations say: 1. **Landmarks:** a navigation region for the console menu, the main region, and a labelled complementary region for the detail panel. 2. **Headings:** the page title at level 1; *Instances* and the panel's instance name at level 2; panel sections such as *Networking* at level 3. 3. **Focus order:** filter bar, table, then the panel's close button and contents; opening the panel moves focus to its heading. 4. **Names:** the refresh icon is *Refresh instances*; each row's actions menu is *Actions for web-01*. 5. **Focus destination:** closing the panel returns focus to the row that opened it; deleting that instance moves focus to the table heading, because the row no longer exists. ## The same annotations on native mobile Nothing here is web-only. A native app also marks elements as headings, groups a card's parts into one element so a screen reader reads it once, sets the order the screen reader's swipe gesture follows, and gives icon buttons accessibility labels. One annotation set serves every platform's implementation. ## How annotations travel Mature systems ship an **annotation kit** in the design library — numbered focus markers, heading tags, landmark outlines, name callouts — so annotating is fast and consistent, and engineers learn one visual language. The annotations are reviewed with an engineer before build, because a question asked at handoff is far cheaper than a defect found in an audit.

  • Should a designer number the focus order of every element on every screen?
    No. Annotate where the order is ambiguous or deliberately departs from the layout's natural reading order: side-by-side regions, detail panels, floating action areas, content inserted on demand. Where the code order already follows the layout, blanket numbering adds noise and goes stale the first time the screen changes.
  • Why is a Stop button on every table row an accessibility problem when sighted users can see which row it belongs to?
    A screen reader user moving through the buttons, or listing them, hears Stop, Stop, Stop with no row context. The annotation gives each a name that starts with the visible word and adds the row's identity — Stop instance web-01 — so it stays unique, and because it still contains the visible label, speech-input users who say Stop can still reach it.

saying these in an interview costs you the question

  • Focus order always follows the visual layout, so it never needs annotating.
  • The largest text on a screen is automatically its top-level heading.
  • An icon-only button's name should describe what the icon looks like.
  • Accessible names should include the word button so users know it is clickable.
  • Accessibility is decided at implementation, so designs need no accessibility notes.