By Mehdi HassanWhat are design annotations and why do developers need them?
Design annotations are short notes on a design file that explain behavior a static frame can't show. A frame shows what a button looks like. An annotation says what happens when it's clicked twice, what it says while saving, and where focus goes afterwards. Developers need them because every unanswered question becomes a guess in code.
Annotations are one layer of a complete design-to-development handoff. They work best when the file is already organized, components are built properly and the obvious states are drawn. Their job is to cover the rules that are left, not to replace missing design work.
What should design annotations cover?
Design annotations should cover four things: states, interactions, content rules and accessibility. Leave visual specs such as spacing, color and type to the inspect panel or Dev Mode, which read them straight from the file and are always current.
Note type | What it explains | Example |
|---|---|---|
State | How the element changes with data or status | Shows a skeleton for the first load, cached data on refresh |
Interaction | What happens on click, hover, drag, keyboard or timeout | Escape closes the drawer and returns focus to the trigger |
Content rule | Limits, truncation, formatting and fallbacks | Names truncate after one line with full name on hover |
Accessibility | Labels, reading order, focus and announcements | Error message is announced and linked to the field |
Open question | A decision not yet made, with an owner | Do archived projects appear in search? Owner: PM |
The fifth type, open questions, matters more than it looks. Marking unknowns explicitly stops developers from treating a gap as an approved decision, and it gives the product owner a list to clear before the build starts.
How do you build a design annotation kit in Figma?
Build an annotation kit as a small set of Figma components that look nothing like your interface, so nobody mistakes them for UI. Keep it in your library and use it in every file. A kit takes an hour to make and saves that time on the first feature.
Create a numbered marker
A small circle with a number that sits on the element being described. Use one color that doesn't appear in your product.
Create a note card with a type property
One component with a variant for each note type: state, interaction, content, accessibility and open question. Each variant gets its own label and color.
Add a connector or place notes beside the frame
Keep notes outside the screen frame so they never get exported or inspected as UI, and match marker numbers to card numbers.
Add a flow arrow
A simple arrow component for showing what leads where between frames, labelled with the trigger.
Document the kit on the read-me page
Show one example of each note type, so new people copy the pattern instead of inventing their own.
Figma also has native annotation features in Dev Mode that attach notes and measurements to layers. If your team works in Figma Dev Mode, use them for property-level notes, and keep the component kit for flows and multi-step behavior. Either way, keep annotations next to the ready-for-dev screens described in our guide to Figma file organization.
Which edge cases do developers always ask about?
Developers ask about the same edge cases on almost every feature, so answer them before handoff. Draw the important ones as frames, and annotate the rules for the rest.
- Empty: no data yet, no results for a search, everything filtered out. Each needs its own message.
- Loading: first load, refresh, pagination and slow responses. Which parts show skeletons and which keep old data?
- Errors: validation, network failure, server error and permission denied, with the exact copy for each.
- Long and short content: the longest real name, a one-word title, a missing avatar, numbers in the millions.
- Many items: what happens at 3 items, 30 and 3,000? Pagination, virtual scrolling or a limit?
- Permissions: what a viewer sees compared with an admin. Hidden, disabled or explained?
- Destructive actions: confirmation, undo, and what happens to related data.
- Interrupted flows: closing a modal mid-way, going back, refreshing the page, a session expiring.
- Keyboard and focus: tab order, focus after an action, and how to close overlays without a mouse.
How should you write interaction and state specs?
Write interaction specs as trigger, response and end state, in one or two plain sentences. "On submit, the button shows Saving and is disabled. On success, the drawer closes and a toast says Changes saved. On error, the drawer stays open and the message appears above the form." That format is quick to write and easy to test.
Hypothetical example: annotating a file upload field
For example, suppose a form has a file upload field. The designer draws four frames: empty, dragging over, uploading with progress and uploaded with a remove option. Then come the annotations. Note 1 (content rule): accepts PDF and PNG up to the size limit set by engineering, and the file name truncates in the middle so the extension stays visible. Note 2 (interaction): dropping an unsupported file shows the error frame without clearing previous uploads. Note 3 (accessibility): the drop zone is also a button that opens the file picker, and upload progress is announced. Note 4 (open question): can users upload more than one file? Owner: PM.
Four frames and four notes answer every question a developer would otherwise raise in a thread.
For motion, give the trigger, what moves, the duration and the easing, and link a prototype if timing matters. For responsive behavior, write the rule rather than drawing every width, and let auto layout settings that map to CSS carry the rest.
How do annotations fit with the rest of your handoff?
Annotations sit between a well-built file and a design QA pass on the finished build. The file provides components and layout, the annotations explain behavior, and the review checks that both made it into code. Skip any one and the other two carry more weight than they can.
Before handoff, run the Figma handoff checklist. After the build, review it with a design QA pass. And if annotation keeps turning into long threads, it's worth reading why design handoffs fail and what changes when one team owns both sides. That's how we run our own projects, starting with a fixed $3,000 brand and design sprint when a product needs direction first.
