The annotation problem in design handoff

Here's a thing that happens in almost every design handoff I've ever been part of: the designer spends three hours annotating a Figma file. The developer opens it, looks at the annotations, and then asks the designer directly anyway.

This is not a developer problem. This is an annotation design problem.

Why Annotations Fail

We annotate for ourselves, not for the reader. Annotations tend to explain what we were thinking during design. Developers need to know what they need to build. These are different documents.

We put the annotation next to the thing it describes. The natural instinct is to label elements inline. But developers don't read Figma files the way designers do. They jump around looking for specific information. If the spec for a button state is embedded in a corner of a frame they haven't found yet, they'll ask you.

We annotate happy paths. Empty states, error states, loading states, disabled states — these are the states that take engineering effort and where bugs live. Most annotation layers describe exactly the state you'd present to a CEO demo. The edge cases go unannotated because we designed them last and were tired.

What Works Instead

Write a spec, not a label. Instead of an arrow pointing to a component saying "dropdown," write a sentence: "This dropdown populates from the user's saved team members. If the list is empty, show 'No team members added yet' with a link to team settings." That's what a developer actually needs.

Annotate states, not components. For every interactive element, document the states: default, hover, active, disabled, loading, error, empty, success. If you can't list all the states, you haven't finished designing it.

Create a separate handoff doc. The Figma file is the visual reference. The handoff document is the specification. Conflating them creates noise. A Notion page or a comment thread structured around user stories reads better than a Figma annotation layer at 30% zoom.

Put yourself in the PR review. Before calling a design "ready for handoff," ask: could I review a pull request against this spec and know if the implementation is correct? If the answer is no, the annotation isn't done.

The Real Problem

Design handoff is a communication problem wearing a tooling costume. Better annotation tools won't fix it. The underlying issue is that designers and developers have different mental models of the same artifact.

The annotation layer is a translation. Write it for the reader.