As a web designer, have you ever been bombarded with questions about your design specs? Imagine the project you’re working on is nearing the implementation phase, so the developers on your team are starting to ask more specific questions. They might ask: “What happens to this element on hover?” or “What happens in between this screen and the next?”
Luckily, you’ve already thought about these scenarios and quickly answer their questions. However, this happens more than a few times and starts to take up your time and energy to constantly respond to these questions.
A lot of these types of questions and conversations can be avoided by being more proactive in your design specs. One way that designers can communicate their ideas more clearly and proactively is through web design annotations. Design annotations are
brief, written explanations provided with design deliverables in order to define & describe aspects of the design.
— Dan Lachapelle in Design Basics: Annotating Your Work
Why annotate?
Annotations in design can remove a lot of uncertainty about how experiences work. And the best thing about them is that they’re right there in context. A designer can make developers on their team happy by adding annotations that make things a little more clear.
Recently, I’ve been thinking about how I can be more intentional in my design specs by providing useful annotations, and I’d like to share my learnings. When you work with remote engineering teams like me, annotations can save time by proactively answering potential questions about your design. Questions that would’ve remained unanswered in a 10-hour span due to time differences could be addressed by some simple annotations.
Plus, annotations aren’t only useful for developers — they provide context for any stakeholders that may review your designs. They can even serve as good reminders for yourself as the designer and encourage you to formulate your intentions and rationale into words. Annotation vs documentation
To be clear, this article won’t cover design documentation, which typically lives outside of the design mockups and acts as a source of truth for the project’s background, research, and the rationale behind certain design decisions that were made. Annotations by no means replace the need for design documentation — rather, they compliment each other. For this article, I’ll be talking specifically about design annotations that are actually embedded within a prototype or mockup. You can read some great articles about design documentation linked below.
When to annotate?
We can’t (and shouldn’t) annotate everything. Annotating takes additional time and effort, which you should always consider whether or not to invest. And the more annotations there are, the less important they become. However, there are some specific scenarios where adding annotations may be useful:
Showing error and edge casesDescribing off-screen experiences
Sharing design rationale
Tracking changes and decisions
1. Showing error and edge cases
Let’s say you’re designing a workflow in which a user uploads a file. If the upload fails due to a server timeout, you should show an error that the upload failed. Since this is a relatively simple error case, instead of repeating the flow again to demonstrate the error case, you can branch off of your main “happy path” to briefly take the audience to the error state with a route back. It’s similar to a choose-your-own-adventure book where certain paths lead to dead-ends, but you can always flip back to the main storyline.
The way I like to demonstrate this is with a toggle annotation that stakeholders can use to turn on and off the error state. This ensures they always have a way back to the main workflow.
2. Describing off-screen experiences
Not all user experiences happen on-screen. Many workflows involve events and processes that happen off-screen, even right in the middle of a on-screen workflow. For example, a food delivery service involves a physical in-person process of the delivery agent handing the food over to the customer. It starts off with the customer making a request on-screen, then the food delivery happening off-screen, and finishes with the delivery agent marking the delivery as complete and the customer rating the service on-screen.
While the majority of this process probably should be explained extensively somewhere in your design documentation, you can use annotations that link to the design documentation so that it’s within the context of the workflow. It could even link directly to the section that talks about the relevant off-screen process. This saves time spent digging up the right link and searching for the right sections to find answers.
On the other hand, if the off-screen experience is very brief and easy to explain in a few bullet points, an annotation might suffice.
3. Sharing design rationale
If a particular part of your design has raised questions, it might be helpful to add annotations that provide design rationale. This is particularly helpful when you run into technical limitations and compromises had to be made in the design.
Returning to our file uploading example, let’s say there is a file size limit of 50MB per file. Your ideal design was to show immediate feedback to the user before the file even starts uploading that the file is too large to upload. However, it turns out that it’s difficult for the developers on your team to detect this in advance. It’s not ideal, but you adjust your designs accordingly to show an error after the file fails to upload. This is a good opportunity to explain your design rationale through an annotation.
In the example annotation above, you’ll notice a “See explorations” link. For those who are interested, they can click this link to see your previous iterations to better understand your design rationale and how you landed on the final design.
4. Tracking changes and decisions
When your designs change, sometimes it’s helpful to leave a date stamp of when these changes happen and why. It helps you and others remember the context of when and why a decision was made to change the design.
Imagine you had a meeting two weeks ago in which it was decided that the date the file uploaded (Oct 18, 2019) should be changed to relative time lapsed since the file was uploaded (2 weeks ago). It‘s a small change that may go unnoticed for your developers who may or may not have been part of that meeting. An annotation can help point out the change and also provide a reference for when and why that change happened.
How to annotate?
There isn’t a “right” way of doing design annotations. You could have them right in your designs or on a separate sheet with numbered labels. Maybe you use the comment features built into whichever design tool you use for annotations. Personally, I use comments more for conversations rather than annotations because comments are typically hidden by default and thus not as discoverable.
You should do what works for yourself and your team. But if you’ve never done annotations before, here are some Figma components to get you started: Figma library of basic design annotations to get you started
Introducing your annotation system
Once you start adding annotations to your designs, have a short meeting or write up something to introduce annotations to your developers and stakeholders. This will prompt them to start looking out for your annotations and additionally build rapport with your developers, since you’re making the effort to make their jobs easier.
Otherwise, they may be confused by them or they might even think it’s part of your design (speaking from personal experience). I didn’t formally introduce annotations to the developers on my team, and one of them ended up implementing a pink toggle button in our UI that was only for toggling on and off an error state for demonstration. At the time I was horrified, but looking back now I don’t think I would really mind having a pink toggle button…
Design systems make this easier
It’s worth mentioning that design systems reduce the need for annotations. They do a lot of heavy lifting in terms of predefining the behavior of components. Design systems make it so that certain components don’t need additional explanation, since their behaviors are already well defined and built into the code. This is an advantage, and gives more opportunity for designers to focus on explaining aspects around the actual workflow through annotations. At VMware, we have an open-source design system called Clarity, and libraries that designers can leverage to quickly build their designs. Here is our Figma community page where you can access our Clarity Figma libraries:
Annotations sweat the small stuffAs much as annotations can help, they can’t explain everything. Annotations can cover the details, but the big picture often lies in design documentation. Although I use annotations to sweat the details, I depend on design briefs to cover the full context.
Hopefully these tips will help you be successful when using design annotations, and most importantly make your developers (and other stakeholders) happier. If you have other tips you’d like to share from your experiences with design annotations, please leave them in the comments below!