How to Annotate Designs for Developer Handoff

Annotations are the notes you leave on a design to explain things that aren't obvious from looking at it. Done well, they save hours of back-and-forth with developers. Done badly, they either state the obvious or leave out the things that actually matter.

The rule: annotate behavior, not appearance. Developers can read spacing values and colors from the design file. What they can't read is what should happen when the user does something unexpected, what the empty state looks like, or how this component should behave on a screen reader.

What to annotate

Interaction notes. Anything that moves, transitions, opens, or responds to user input. "Clicking this button opens a modal" is worth documenting. "Hovering shows a tooltip with this text: [copy]" is worth documenting. The animation curve, duration, and easing for a transition.

Edge cases. What does this screen look like with 0 items in the list? With 1? With 1,000? What happens if the user's name is 80 characters long? What does the error state look like if the API call fails? These scenarios don't appear in your main flow screens but developers need to handle them.

Error states. Every form input needs a specified error message and error state design. "Input error state — show inline message in red below the field: [error message copy]." Don't make developers guess.

Accessibility notes. Screen reader label for icon-only buttons. Tab order for complex components. Focus management for modals (focus should move to the modal on open; return to the trigger on close). ARIA roles for non-standard components.

Copy that isn't finalized. Flag placeholder copy that needs to be reviewed. Mark anything that needs localization.

What not to annotate

Don't annotate things the file already communicates. "Text is 16px" — the developer can see that. "Background is #F5F5F5" — they can sample it. Over-annotating is just as problematic as under-annotating because it buries the important notes in obvious ones.

Setting up an annotation layer convention in Figma

Create a dedicated layer structure for annotations so they're easy to find and easy to hide.

A standard setup:

• Create a frame over your screen at the same dimensions
• Name it "Annotations" and keep it as the top layer in the screen's frame group
• Use a consistent annotation style: a numbered badge (circle with number) pointing to an annotation card, or a sticky-note-style label

Figma doesn't have a built-in annotation tool, but several plugins handle this well. "Figma Autoname" keeps layers organized. "Annotations Kit" adds a purpose-built annotation layer system. Some teams build their own — a simple component library with numbered badges and text cards works fine.

The most important thing is consistency. Pick a system and use it on every file. Developers should know exactly where to look.

Creating an annotation layer convention

Use a separate page for detailed annotation specs if you have complex interactions:

• Page 1: Main design screens (clean, presentation-ready)
• Page 2: Annotated versions of the same screens
• Page 3: Component states (all variants side by side)
• Page 4: Prototype flows

This keeps the main design pages clean for stakeholder reviews while having complete developer documentation available one click away.

What developers actually need to know

From experience building handoff processes with engineering teams, the things developers most often ask about that weren't documented:

1. What triggers this state? (Not just what it looks like)
2. What's the behavior after this action? (What happens next in the flow)
3. Is this a one-time interaction or does it persist?
4. What's the mobile/responsive variant?
5. What's the error state?
6. What are the animation timings?

If you answer these for every significant interaction in your annotations, you'll eliminate most handoff questions before they're asked.

Zeplin as an alternative

Zeplin sits between Figma and developers and adds its own annotation layer on top of design files. You can add notes, link to design guidelines, and create "sections" that group related components together.

The advantage over native Figma annotations: Zeplin's interface is built specifically for handoff, so developers get a more structured view without needing edit access to your Figma file. The tradeoff is maintaining two systems — changes in Figma need to be re-synced to Zeplin.

Try Zeplin

For teams where developers aren't in Figma daily, Zeplin can reduce friction. For teams that are already comfortable with Figma Dev Mode, the built-in tools are usually enough.

The annotation that saves the most time

If you do nothing else, annotate your empty states. It's the single most common thing missing from design handoff, and it's the first thing users encounter when they create a new account or clear their data. Designing it into the spec saves a developer from having to invent it — and an empty state invented by engineering is usually a plain text label that nobody's happy with.