Design documentation: A practical guide

We’ve all been there. You made a design and you want to share it with the right people, probably developers. But designs on itself are not self explanatory, although we sometimes think they do. How many times have we experienced that the end result is not build exactly how we envisioned it? Or that there was a misinterpretation of the designs? Or that the developers were not able to find the right designs?

Designs need to be documented in such a way that they are accessible, easy to read and clear for everyone so we limit the risk of mistakes and unclarity. In this article I want to guide you through the process of design documentation.

You will learn..

1. Why it is essential to use design documentation.
2. How to use an awesome design annotations library.
3. How to use the annotations library in Figma (and other tools)
4. And how you can deliver a specification brief to developers.

Why design documentation?

First of all: we document designs to explain how the design works, not what the design looks like. You use it to explain interactions and flows. But also for example how copy works, or metrics.

Part of the work of a designer is of course to make designs. Usually features, improvements or any other type of design. It’s how we shape an application and where we define how something looks and works. Explaining how the design works is an essential step in the design process. This is called design documentation and for this we use a specification brief.

Specification brief

The specification brief is THE shared file between designers and key stakeholders. To name a few: developers, product owners, data engineers, CRO specialists, designers, management, etc.

It contains a visual representation of the screen designs + annotations that explain all details needed for a developer to develop the screens right. A well specified brief is self explanatory and should give developers enough guidance to build the designs.

Why it’s so important to have a specification brief?

• Efficiency — A specification brief reduces questions from developers and it increases speed in delivery. It avoids refinement sessions and mistakes in development.
• Quality — It helps you as a designer to actually think about how your designs should work. How often did you get a question from a developer, while actually not knowing how the interaction should work?
• Retrievability — It helps you remember later down the road why you made certain decisions. Especially when building complex applications, you tend to forget them. Not only for yourself, but also for the rest of the design community.
• Accessibility — A unified way of annotating your designs helps you to create a shared standard in documentation. In other words: every stakeholder can and should be able to read any brief easily. For example: when referencing in backlog stories, or for presentations.
• Visibility — Not only can you use the specification brief for developers, but other stakeholders can access the briefs as well.

What does a specification brief look like?

Within Randstad we deliver our specification briefs using Confluence. The reason for this is that all key stakeholders in the organization are using it and they are familiar with this. A great benefit of Confluence is that everyone can make comments, edit pages and use the search functionality as well. Regardless your choice of platform, always keep in mind that for delivering a specification brief it’s important to keep the threshold low for your key stakeholders.

Below that you are documenting the actual designs. Below you can see how a specification brief could look like. As you can see I copy & pasted everything in separates column. The key sections you can see are:

1. Summary — This consists of people involved, a link to the Figma file and a table of contents. Think of all the practical things that are useful.
2. Design Rationale — Explaining key rationale behind design decisions. They help everyone be aware of WHY you made certain decisions. This improves retrievability.
3. Flows — When needed, provide a flow on how the feature works and behaves. Often a flow is fundamental for a feature and gives a high level understanding of the feature.
4. Screens— These design screenshots coming from your design tool that have the markers on it. There is a columns for both mobile as well as desktop.
5. Descriptions — This is where you explain every bit of what is on the screen so it is clear for your reader.

This is how a specification brief at Randstad looks like:

Now you know what a specification brief is, let’s jump into the design annotations.

The Design Annotations library

I want to give you a simple example first. This lo-fi example — designed in Figma — contains almost all types of annotations. This gives you an idea for context and how to look at it from a holistic perspective. For this example I am explaining how a calendar selection works on mobile. This is how it would look like:

There is a lot going on, but let me first say this: the design of the annotations is freaking ugly. That’s on purpose. We don’t want the annotations to look too fancy and interfere with the actual design. There is a big chance you don’t use these colors in your visual design, so it distinguishes well. That said, you can use annotations to explain both lo-fi concepts, as well as hi-fi designs.

Let’s go over the most important types of annotations.

Screen ID’s

Every screen must have a screen ID. These screen ID’s help you discuss screens with any stakeholder. You can place a screen ID on top of a design art board. Make sure to give the art board the same name as well.

Let’s take a look at the example above. If these screens wouldn’t have an ID, we would probably be talking about ‘the screen with the unselected calendar’. This could work, but the moment you have another screen with an unselected state, there could be misalignment. Screen ID’s avoid this.

The naming convention for a screen ID is: <device-FLOW INITIALS-unique number>. In our examples case the device is mobile and the initials are CV, meaning: Calendar View.

The numbers give you a range. The goal is to leave enough space in between to add extra screens later. Let give some examples:

• AB-0010 range — I have space for 9 screens before I hit AB-0020. If I had already started a set of screens with AB-0020, I would be stuck.
• AB-0100 range — I have space for 99 screen before I hit AB-0200. This gives me a lot of space.

Depending on the amount of screens and flows in a design file, you can pick your structure. Ultimately the goal is to give every screen a unique ID.

Markers

There are 3 types of markers. Because markers are overlapping layers, you want them to position well. That’s why you can choose to let them point into all directions. This gives flexibility in positioning them. Awesome isn’t it!?

All markers are linked to notes. More on that later. Let me explain the types of makers first.

Explanation ID’s

Use explain ID’s to explain how interaction and states work. The are filled using letters. Every marker has a unique number, but the same letter can be shown in multiple screens if it explains the same thing. In the example above you can find ‘C’. This marker explains the state of the main call to action. Explaining this covers 2 screens, therefore I have 2 C’s.

Text ID’s

Text ID’s mark fields or areas of text. They can be used to say something specific about text. Usually they come in very handy when using translations. You can mark a piece of text with an ID, so you can refer to it in any other file.

Metrics ID’s

Metrics ID’s can be used to explain specific metrics you want to apply to the flow. In our example, we want to know the average dates selected per session.

Notes

Notes give you the possibility to explain how the design works using text. You place the notes anywhere you want, but my advice would be to place the on the side of the art boards so you will always have a clear view on the designs. See example above.

5 types of notes

1. Idea (green) — Use to write an idea that you or the team needs to take a look at. It can be removed when delivering a design hand-off.
2. Question (blue) — This is a question that is raised. Use this type of note as a placeholder to remind yourself (or the team) to answer this question.
3. Action point (red) — This is a note type that you can use to write down an action point. This can be something to investigate, or simply something that needs to be added to the design.
4. Note (yellow) — Use a note to explain anything. These notes are linked to numbered or lettered markers.
5. Alternative (orange)— This note can be used to explain an alternative flow or option within the design.

In practice you would use Note and Alternative a lot. Idea, Question and Action Points could also be replaced by software comments or other platforms that you already use.

Good to mention: when commenting we have two ways of doing this:

Comments in Figma — We only use these between designers, not with other stakeholders. This works well when working on a design project together.

Comments in Confluence — Finding comments in Figma can be challenging for key stakeholders. They would have to look for comments and they might miss the overview. Comments in Confluence is something that they are used to and they won’t get distracted by non relevant Figma features.

Flows

Flows are used to explain the flow of a serie of screens. They help you explain choices in the flow and to show action & reaction.

3 types of flows

1. Arrows — Use arrows to visually connect screens, modals or sections. In the example I used an arrow to connect two screens.
2. Booleans — With a boolean you can add logics to the flow by adding choices.
3. Actions — Use a action to show when an action worth mentioning is performed.

Gestures

Gestures are used to show the actual interaction from the user, using a hand or cursor. With this you can visually show what happens when a user hover over a component. Or clicks or taps on a component.

You can also use Highlight area to explain something about a specific area.

How to use in Figma

Now you’ve gotten to the point of knowing what the library consists of, it’s time to start using them.

In Figma we advice to group all design annotations into a mega frame that is bigger than all your collections of artboards, so that it can be on top of everthing and hidden in a single click if you need to. Within this frame we group all types of annotations. This frame sits on top of your Figma art boards. Setting it up like this has a couple of advantages:

1. Clean artboards — The annotations do not interfere with the designs. The are not going to be part of the screen art boards, so the art boards remain clean.
2. Turning annotations on/off — You can turn all annotations on and off using the eye icon in the layers panel on the left. This is useful if you just want to focus on design.
3. Easy to copy & paste — Copy and pasting the art boards with or without annotations is easy. (Hold command and drag a selection)
4. Overview — Grouping all types of annotations gives an quick overview.

Example

Below you can see an example of all the annotations grouped into a frame and selected. On the left you see the groups: titles, markers, notes, flows & gestures and screen ID’s. The annotations frame is on the top and turned on.

Below you can see an example of how the design file looks when the annotations frame is hidden. This allows you to design more easily.

Regardless which tool you use for designing your experiences, the principle of using design annotations remains the same.

Closing

I hope this guide helped you get a sense of the importance and that it’ll guide you in using the Annotations Library.

The best part is that the Design Annotations Library available for you as well!

You can download your own copy in the Figma community HERE.

Did you like this article? Please feel free to comment or clap! A big big shoutout to David Güiza Caicedo for creating this annotation library! If you want to read more of my articles I can recommend the one below.

How to let your design system evolve in the right direction