Design Reference Annotations That Separate Facts from Ideas
Annotate a design reference with a precise target, an observation, an interpretation and a proposal. Includes a worked example and a correction method.
Direct answer
A useful design reference annotation names a specific detail and separates what you observed from what you think it means. Attach the note to its target, preserve the source and state any uncertainty. Put your proposed adaptation in a separate sentence so it cannot be mistaken for the original design.
Give the note a target
“Good navigation” does not identify what to inspect. “The section label remains visible above the open menu” does. A target can be an element in a screenshot, a region of a page or a timestamp in a recording. Include enough context for another person to find it without searching the whole reference.
The W3C Web Annotation Data Model distinguishes an annotation's body from its target. That is a useful conceptual distinction for a manual note: the comment is one thing, the part of the source it refers to is another. This guide uses that idea; it does not claim that Sesavu implements the standard.[1]
Keep the source URL and capture date with the target. If you crop an image, retain a link or identifier for the wider capture so the detail is not detached from its setting. Source history belongs in the provenance record; the annotation should explain the particular detail worth discussing.[3]
Use four fields for four different jobs
Write the observation before the interpretation. If you cannot describe what is visible or what happened, the note may be only a preference. That can still be useful, but label it as a preference rather than evidence.
- Target: the exact element, region or moment and its source context.
- Observation: what was visible or what happened under the recorded conditions.
- Interpretation: what you think the detail may communicate, with uncertainty intact.
- Proposal: what you want to try in your own design, plus the question it should answer.
Use common language for behaviour
TetraLogical's annotation guidance calls for documenting behaviour that a visual design alone may not explain, including focus, keyboard interaction, state changes and layout. Its examples use common language to connect an action with an expected result. A note should be understandable without guessing the intended implementation.[2]
For a reference, keep observed and expected results distinct. “When I activate the menu button, the panel opens” describes an interaction you performed. “When the menu opens, focus should move to its first item” describes a proposed requirement unless you verified it. Do not turn a static screenshot into an interaction report.
Use the same distinction when writing for a developer or AI coding agent. Name the behaviour you want, and identify the reference detail that motivated it. Avoid asking for a visual clone with hidden assumptions about keyboard use, errors or data.
Worked example: a filter panel
This example is fictional. You have a screenshot of an open filter panel. A selected option has a dark outline, and an action labelled “Apply filters” appears at the bottom. The screenshot does not show what happens when an option changes.
An initial note says “filters update the results immediately”. That is not supported by the screenshot. Correct it to “an Apply filters action is visible; update timing is unknown”. Keep the correction with the note so the earlier assumption does not reappear in a brief.
- Target: the selected option and bottom action in the open-panel screenshot.
- Observation: the selected option has a dark outline; an Apply filters action is visible.
- Interpretation: the panel may collect changes before applying them; this is unverified.
- Proposal: compare an explicit apply action with immediate updates in our prototype.
- Check next: change an option in the source interface, if available, and observe when the results change.
Keep the note small enough to challenge
One annotation should make one inspectable point. Split a long note about spacing, colour, focus and navigation into separate targets. Then ask whether each interpretation follows from its observation. A claim such as “this makes users trust the product” needs evidence beyond the appearance of the reference.
When new evidence contradicts a note, update the observation and record why the interpretation changed. Do not silently rewrite an uncertain guess as if it had always been a fact. If the source is no longer accessible, keep that limitation visible.
Only after the notes are clear should you combine them into a design brief. The brief can choose a direction; the annotations preserve the individual reasons and uncertainties behind it.[4]
Questions designers ask
What is the difference between an annotation and a caption?
A caption usually describes an image as a whole. An annotation points to a specific detail and adds an observation, explanation or question. Both can be useful when their purpose is clear.
Should I annotate every visible detail?
No. Annotate the details that affect the decision you are making or that someone could easily misinterpret. A small set of precise notes is easier to challenge than a page covered in labels.
Can an annotation contain an opinion?
Yes. Label it as an interpretation, preference or proposal. The problem is not having an opinion; it is making the opinion look like an observed fact.
Sources checked
- Web Annotation Data Model — W3C
- Annotating designs using common language — TetraLogical
- Design reference source provenance — Sesavu
- Turn visual references into a design brief — Sesavu