đŸ‘‹đŸœ We wrote a book! Order Wireframing for Everyone today →

Balsamiq

Toggle navigation

What Are Wireframe Annotations and Why Use Them?

5 min. read

The goal of wireframe annotations is to make understanding how and why something on the screen should work as clear as possible to anyone viewing your wireframes.

Annotations are the information provided by you, the wireframe's designer, on how something on the screen should function. They can include details outside of the visuals, such as design rationale, scenarios, edge cases, or examples.

Annotations have a challenging role: to speak for the wireframe’s designer when she isn’t there. In theory, when developers or clients want to know just why that link was placed in that spot, they can read the note on the document and understand not only what the thing does, but also why.

The goal is to make the understanding of how and why something should work as clear as possible to anyone viewing the wireframes.


Who are annotations for?

"There are typically five audiences for wireframes: clients (internal or external), developers, visual designers, copywriters, and, most importantly, your future self."

- Dan Saffer

It is your responsibility to communicate the rationale of your design decisions to your client (either internal or external).

  • Clients will want to see that you’ve incorporated the business goals they provided.
  • Developers want to see what they have to support, and how the site or application works (and doesn’t work).
  • Visual Designers want to see what visual elements need to be on the page.
  • Copywriters want to see what they need to write.
  • The future you needs to remember why you made that form element a checkbox instead of a radio button.
Callouts (curly braces here) can indicate content or copy for other consumers of the wireframes.

Why use annotations?

Annotations help clarify how something should work that is represented in a static wireframe. While you can indicate that something should be interactive, such as a button, the developer doesn't know what to make that button do without your explanation. When looking at a static screen it is easy to make assumptions about what something does or what the content should be for that element. Help out your developer friends, and be clear about what you want an element to do.

Wireframe of a web page with numbered notes pointing to a table with relative annotations.
Include reasoning or scenarios to back up your decisions.

How to create annotations

Separate your annotations into 2 main sections: content and functionality.

Developers will mainly look at the functional notes, copywriters the content ones, and everyone else will pick and choose between both.

Be smart about what you put in the wireframe and how. The clearer you make the actual wireframe, the less you will have to explain in annotations.

Annotations are often shown using numbers. The numbers in the wireframe should have a sharp enough contrast (generally with a circle around them) to stand out from the design. The numbers are then listed again on the side or bottom of the wireframe with the text explanation.

Simple wireframe of a web page with numbered callouts and relative annotations on the side.
Indicating what the element on the page is in each annotation is a small, but useful thing.
You can include example text in multiple ways. Just make sure the text you include and its intended use are clear.

What to annotate

  • Any items that are conditional — when and how they should be displayed.
  • Links and buttons — what happens when they are clicked, hovered over, tapped, and visited.
  • Anything that, due to space, could not be shown on a wireframe, e.g., every item on a long drop-down menu.
  • Anything with a business, logical, or technical constraint — e.g., the longest possible length of a password field.

Annotations have to capture not only what is being displayed (and where and when), but also why. The more you can document your thought process and the decisions you made, the easier it is to explain your work, justify your choices, or fix it in case you’ve made a wrong decision.

There is a vast difference between an annotation that reads, “Show first 10 new messages” and one that reads, “Due to possible hundreds of new messages, only show the first 10.”

Sometimes the reasoning is too complicated to put into an annotation, in which case I usually create a separate, attached document that shows the decision process, usually in user flow format.

Example of annotations on a web page wireframe showing different types of functionality.

When to annotate

There are 2 minds of when to annotate your wireframes:

  1. As you are designing
  2. After you finish all of your wireframes

Annotating as you go along and are doing the design helps you think through how something is going to work. If you annotate after you have finished all of your wireframes, you may have forgotten how you intended something to work or what your thought process was behind a decision.

Level of annotations

Like building a product or service, annotating your wireframes is an iterative process. Maybe you are in a brainstorming session and sketching on the whiteboard various ideas. You may have a few annotations to call out the functionality of what you are thinking at a first pass. Maybe you are sketching on paper and you are trying different layouts of a screen. Add a couple of comments so you know what you were thinking as you went through those ideas.

As you move into digital tools, your annotations will become more detailed and laid out cleanly with your designs. When you talk with developers, you'll learn a bit more about what's needed and technical feasibility. It helps to add these notes to your annotations as well.

Level of detail:

  1. Ideation (sketch) — comments on ideas, personas, and scenarios.
  2. Low-fidelity wireframes (sketch/digital) — initial design decisions and explore various UI options.
  3. Medium fidelity wireframes (digital) — basic functionality and layout reasoning.
  4. High-fidelity wireframes (digital) — in-depth functionality and content decisions. Design decisions and scenario rationale.

Some tips & tricks (Q&A)

  1. What if I can't talk to the developers?
    Do your best to explain how you would like something to work. Don't worry about the technology itself, but the animation and functionality that is happening on the screen will need to be very clear.
  2. What if I don't have any research to back up my decisions?
    Look to already solved problems, best practices, and do as much usability testing as you can.
  3. What if I run out of room on the canvas, artboard, etc. to annotate?
    If you have more words that don't fit on the side or the bottom of the page, don't be afraid to start a new page and keep going. Each new screen has its own set of annotations and should start with a 1. Be as clear as you possibly can in your annotations to get your ideas across to someone you may not be able to speak with.

Summary

Some key points to keep in mind when doing annotations are:

  • Annotate your thoughts as you design
  • Know who your audience is for your annotations
  • Write clearly and succinctly

By Julia DeBari
Got questions or feedback? Email learn@balsamiq.com.


Related Articles

What are wireframes and why are they used?

A comprehensive guide to user interface wireframes. Learn what wireframes are, why they matter, and how they’re used through examples and demonstrations.

By Peldi Guilizzoni

Ten Principles of Effective Wireframes

Guiding principles to help designers wireframe better and encourage the entire team to participate in the design process.

By Billy Carlson

Wireframing User Flow with Wireflows

A wireflow is a hybrid design document that combines wireframing with flow diagramming. They are essentially wireframes showing user and system flow.

By Mike Angeles

6 min. read

Get the Inside Scoop!

Want to get exclusive early updates on our
Products, Wireframing Academy, and our Company?

Subscribe to our monthly newsletter and be part of our Inner Circle!

See what people think of our past issues!

Dazz Knowles
"Of all the e-mail newsletters I get, @balsamiq is the one I always read, they're brilliant!" - Dazz Knowles
M. Pesente
"It's always a big pleasure receiving such an inspiring newsletter. Love the Balsamiq culture!" - M. Pesente
Jérémie André
"Another great newsletter from @balsamiq!! 😁" - JĂ©rĂ©mie AndrĂ©
Looking for more ways to get closer to Balsamiq? Join our Research program or Slack community!