Annotation

Origin & evolution

The word comes straight from architecture and print, where reviewers marked up drawings in red pen and the marks were called redlines. The practice carried into software as a literal discipline: a designer would export a static mockup and overlay measurements, hex values, and behaviour notes by hand so an engineer could reproduce the screen faithfully.

Tools then automated the tedious half of it. Zeplin, launched in 2016 to bridge Sketch and engineering, and later Figma's Dev Mode, generate dimensions, colours, and spacing on inspection, which retired most manual redlining. What automation does not generate is the part that needs🫀NeedUserA user need, pain, desire, or constraintView reference → a human: why a button is disabled in this state, what the empty case should say, how a transition should feel. As one practitioner account puts it, a thorough handoff annotation for a single screen can take longer than the design itself. The annotation has narrowed to the judgement layer, the decisions⚖️DecisionStrategyA recorded decision with context, rationale, and consequencesView reference → an inspector tool will never infer.

How it works in practice

A designer hands off a checkout screen. The auto-generated specs already give the engineer 16px gutters and the brand green at #1a7f5a. The annotations carry everything else: the pay button stays disabled until all three fields validate; the error toast appears inline below the card field, not at the top; on a failed charge the form retains entered values; the success transition runs at 200ms ease-out. Six notes, none of them derivable from the static frame. The engineer ships without a single clarifying message, because the questions were answered before they were asked.

Annotation vs. its neighbours

• Interaction spec🖱️Interaction SpecDesign SystemA specification for an interaction behaviourView reference → describes a behaviour formally and reusably: the canonical rules for how a component responds to input, owned by the design system🧰Design SystemDesign SystemThe root design system entityView reference →. An annotation is local and situated, a note pinned to one screen at one moment in a handoff.
• Design component🧱Design ComponentDesign SystemA reusable UI componentView reference → is the reusable unit being annotated. The annotation references the component and says what is specific about this instance of it.
• Prototype is the clickable artefact the annotation marks up. The prototype shows the flow; the annotation explains the parts of the flow that a click-through leaves ambiguous.

In the graph

In the Unified Product Graph, an annotation lives in the design-system region and attaches through prototype_annotated_with_annotationPrototypeannotated withAnnotationhierarchy. Modelling the note as its own node keeps handoff intent first-class and queryable, so a screen's open questions are visible rather than buried in a comment thread that disappears when the file is archived. It also lets an annotation point at the design_component🧱Design ComponentDesign SystemA reusable UI componentView reference → or interaction_spec🖱️Interaction SpecDesign SystemA specification for an interaction behaviourView reference → it concerns, turning a loose remark into a tracked link between what was drawn and what must be built.