How to Add Annotations in Figma, and What I Write in Them

To add annotations in Figma, you choose Annotation in the toolbar or press Shift and T, select the layer which the note is about, write the note and pick a category, and the note then stays attached to that layer in Design mode and in Dev Mode, which makes annotations the right place for everything that a screen cannot show on its own, such as what happens on a tap or how long a menu waits before it closes. Since the end of September every caption and behaviour note in the website designs which I build has gone into an annotation, so the canvas shows only the screens and the notes travel with the layers which they describe.

This post goes through the steps, the three categories which I use and the way I write each note, since an annotation is mostly read by someone who was not in the room when the design was made.

Annotations and comments do different jobs

Figma describes an annotation as a note attached to a layer, which can hold free text and live properties that stay accurate as the design changes, and it made them for handing a design over to developers, according to its guide to measurements and annotations. A comment is a conversation instead, which ends when it is resolved, and Figma’s own handbook for developer handoff splits the two the same way, with comments for the back and forth and annotations for the details which should stand out to a developer. So I use comments for questions which need an answer, and annotations for anything which should still be true when the design is built.

How to add an annotation

In Design mode, choose Annotation in the toolbar or press Shift and T, then click the layer which the note is about, such as a button, a card or a whole frame, write the note and pick a category from the menu beside it, and in Dev Mode the same tool is called Annotate. Selecting an annotation and pressing Delete removes it, and if the notes are in the way while you design, the View menu in Figma’s main menu has an Annotations item which hides them until you tick it again.

Adding an annotation needs a Full seat with edit access to the file, and Figma lists annotations on its paid plans only, so on most projects the designer writes them and the developers read them.

The three categories which I use

Figma starts each file with four categories, Development, Interaction, Accessibility and Content, and Edit categories in the category menu lets you rename those or add your own, each with a name and one of eight colours. These are the three which I add to my website files.

Caption

A caption says what the frame shows and when a visitor would see it, such as “the search panel open over the home page, with results after two letters”, and it replaces the line of text which I used to place under each screen on the canvas.

Behaviour

A behaviour note says what happens on hover, tap, scroll or the keyboard, with the numbers which a developer needs, such as “the panel waits 200 milliseconds before it closes when the pointer leaves”, which is the delay that I described in my post on dropdown menu UX. One behaviour goes in each note, so a developer can work through them one by one.

Feedback

When a client’s feedback arrives outside Figma, such as a PDF or an email, I copy each point word for word into a Feedback annotation on the layer which it is about, titled after the page of the PDF which it came from, and add a line which says done or to follow. In October I did that for a PDF of 63 sticky notes, each one placed on the layer which its note pointed at, or on the page where a section had since been removed, so the client could open the file and read the answer to every note in the place where they had made it.

Why my captions moved off the canvas

Figma draws a name tag above every frame which sits on the canvas or in a section, and on my boards those tags kept colliding with the caption text which I had placed under each screen, so at the end of September I moved the captions into annotations and gave each frame a name which says what it is, such as Home / Desktop / Search open. The canvas now shows only the screens in a row, and each caption is attached to the frame which it describes.

Write each annotation for the person who reads it

Clients who open the file in Dev Mode read the annotations, and so do developers who join the project months later, so I write each note to stand on its own, with no reference to a conversation, a file or a person which the reader cannot see. In October I found one of my own notes which ended by pointing at a working document that only my team could open, and which talked about the client in the third person, and I rewrote it and four others like it the same day, so that anything still open simply says to follow.

I would also keep each note short and literal, with the state, the trigger and the result in that order, and with numbers wherever a developer would otherwise have to guess, such as a delay in milliseconds, a size in pixels or the number of results which a list shows before it pages. The states which a screen can be in, such as empty, loading and error, deserve a note each, which I wrote about in my post on empty state UX design.

Pin the details which a developer needs

An annotation can also carry properties, such as a width, a fill, a text style or the spacing between items, which you add with + Property, and they update on their own when the design changes, so the numbers in the note always match the design. Figma also has measurements, which you draw between two layers with Shift and M and which stay on the design as a labelled distance, while the measurements which anyone can see by holding Option or Alt work on every plan but cannot be saved or shared.

I would pin the few values which a developer could easily misread, such as the gap between cards or the size of a tap target, rather than every property on the layer, because a note with fifteen values is mostly read as noise.

Where to start

I would pick one screen in your file which changes when somebody uses it, such as a menu or a form, and write one Behaviour annotation for each thing that happens on it, then read the notes as if you had never seen the design. If a note only makes sense with the conversation behind it, it needs rewriting, and when the file goes to review, the reviewers can use comments for their questions, which I explained in how to comment in Figma, while my projects page shows the kind of websites which these notes are written for.

Frequently asked questions

Can view-only users see annotations in Figma?

Figma’s guide says that viewing annotations needs a Full or Dev seat with at least can view access, so a reviewer on the free View seat is not promised them, and I would check which seat your reviewers have before you rely on annotations for anything which they must read.

Do I need a paid plan to add annotations in Figma?

Yes, Figma lists annotations on its paid plans, and adding one needs a Full seat with edit access. The measurements which you see by holding Option or Alt work on every plan, but they cannot be saved or shared.

What is the difference between annotations and comments in Figma?

Annotations belong to the design and stay attached to their layer, while comments are a conversation which ends when each one is resolved, so I use comments for questions and annotations for everything else.

Can I create my own annotation categories in Figma?

Yes, through Edit categories in the category menu of any annotation, where you can add a category with its own name and colour, or rename the four which Figma starts with. Categories belong to the file, and copying annotated layers into another file brings their categories along.