# Design Annotation

Design annotation adds concise implementation-relevant notes to design artifacts so behavior, rules, states, and intent that are not visually obvious remain explicit.

- Type: artifact
- Domain: Experience & interface
- Level: Advanced
- Last reviewed: 2026-09-22
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/design-annotation/>)

## What it means

A design annotation is a contextual note attached to a frame, flow, component, or prototype. It explains information that cannot be reliably inferred from appearance, such as responsive rules, conditional logic, focus movement, content priority, data formatting, animation intent, or links to governing requirements. Annotations complement executable components and conversation rather than duplicating every visible measurement.

## Why it matters

A screen can show one moment but not the rules that produce it. Targeted annotations reduce ambiguity for engineering, content, QA, accessibility review, and future designers. They also force the author to resolve edge cases before implementation, turning hidden assumptions into questions the team can inspect and test.

## When to use it

Annotate novel or consequential behavior, exceptions to system conventions, complex state changes, responsive transformations, and details likely to be misread. Prefer links to stable component documentation for standard behavior. If a prototype demonstrates timing or sequence more clearly, link it rather than describing motion in a paragraph.

## How it works

1. Identify decisions that a reader cannot safely infer from the design's visible state.
2. Use numbered or anchored notes close to the relevant element and apply a consistent taxonomy for behavior, content, accessibility, and data.
3. Write rules and outcomes rather than implementation guesses; include triggers, conditions, edge cases, and priority where needed.
4. Link to the component, requirement, rationale, prototype, or acceptance criterion that supplies durable detail.
5. Review annotations with implementers, resolve questions, and remove or update notes when the source of truth changes.

## A practical example

A mobile filter panel is annotated to state that selections apply only after confirmation, the close action preserves pending choices, result counts update after each choice, and focus returns to the launch button. A separate note links to the standard modal pattern for keyboard behavior, avoiding a second copy of the same specification.

## Where it breaks

Annotations can become cluttered, contradictory, and stale, especially when they repeat token values or component behavior maintained elsewhere. Text alone is poor at communicating complex timing and can prescribe technical solutions outside the designer's knowledge. Ownership, status, and links to stable sources are necessary for annotations to remain trustworthy.

## Common mistakes

- Labeling visible dimensions while leaving conditional behavior and edge cases unexplained.
- Repeating design-system documentation in every file instead of linking to it.
- Writing vague notes such as “make responsive” without rules, priorities, or examples.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/design-annotation/#visualization-design-annotation>)

## Sources

1. [Add Measurements and Annotate Designs](<https://help.figma.com/hc/en-us/articles/20774752502935-Add-measurements-and-annotate-designs>) — Figma Help Center · Product documentation
2. [Guide to Inspecting](<https://help.figma.com/hc/en-us/articles/22012921621015-Guide-to-inspecting>) — Figma Help Center · Product documentation
3. [ARIA Authoring Practices Guide](<https://www.w3.org/WAI/ARIA/apg/>) — W3C Web Accessibility Initiative · Standards guidance

## Related topics

- [Design Handoff](<https://wiki.soroush.uk/topic/design-handoff/>)
- [Design Documentation](<https://wiki.soroush.uk/topic/design-documentation/>)
- [Interaction Patterns](<https://wiki.soroush.uk/topic/interaction-patterns/>)
