Back to Instructables

Annotation Guide

Best practices for documenting wireframes to ensure clarity for developers and stakeholders.

Why Annotate?

Wireframes show the "what" and "where," but annotations explain the "how" and "why." They bridge the gap between static design and dynamic functionality, covering interactions, logic, and edge cases that aren't immediately visible.

Example

1
2
1

Dismissal Behavior

Clicking the 'X' or clicking outside the modal should close it. If the user has unsaved changes, trigger a confirmation dialog first.

2

Primary Action

The "Save" button is disabled by default until at least one field has been modified. Upon success, show a toast notification.

What to Document

  • Interactions: What happens on click, hover, or scroll?
  • Logic: Conditional visibility (e.g., "Only show this if user is logged in").
  • States: Empty states, loading states, error states, and success states.
  • Content Rules: Character limits, truncation behavior, and date formats.
  • Accessibility: Tab order, aria-labels, and screen reader announcements.