artifactExperience & interface

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.

Download Markdown (.md)

01What 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.[1][2][3]

Implementation intent that pixels alone cannot show Attach concise rules to the exact element, state, or transition they explain
Target
The component, state, region, or transition addressed
Behavior
Trigger, response, timing, and state change
Content rule
Source, variation, truncation, and localization
Accessibility
Semantics, name, focus, keyboard, and announcement
Responsive rule
Reflow, priority, and input-context behavior
Edge cases
Empty, loading, error, permissions, and long data

Annotations should clarify behavior, content, accessibility, responsiveness, data, and edge cases without duplicating discoverable specifications or becoming stale.

02Why 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.

03When 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.

04How 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.

05A practical example

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.

06Where 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.

07Sources

  1. Add Measurements and Annotate DesignsFigma Help Center · Product documentationAdd Measurements and Annotate Designs
  2. Guide to InspectingFigma Help Center · Product documentationGuide to Inspecting
  3. ARIA Authoring Practices GuideW3C Web Accessibility Initiative · Standards guidanceARIA Authoring Practices Guide
View saved topics

Start typing to search titles, definitions, categories, and frameworks.