Specs and annotations

Why it matters

"Handoff" sounds like a single moment when you throw a file over a wall. In good teams it is a conversation that starts early and continues through build. Still, at some point engineers need a design they can build from without guessing. Missing details turn into questions, delays and inconsistent results. Clear specs and annotations are how you answer the questions before they are asked.

The core idea: answer what the picture cannot

Modern tools give developers measurements, colours and fonts automatically. In Figma, Dev Mode shows spacing, sizes, variables (tokens) and generated CSS for any layer. (Dev Mode is part of Figma's paid plans; on the free plan developers can still inspect layers with view access, and you can write the same information as annotations.) What tools cannot show is intent: behaviour, rules, edge cases and anything that changes over time.

So annotations should focus on:

• Behaviour: what happens on tap, hover, scroll, submit, success, failure.
• States and edge cases: empty, loading, error, long text, zero, one and many items, offline.
• Responsive rules: what stretches, what wraps, what stacks at small widths, breakpoints.
• Content rules: maximum lengths, truncation, formatting of dates and numbers.
• Data and logic: where values come from, sorting, validation rules.
• Components and tokens used: so developers reuse the system instead of rebuilding.
• Accessibility: covered in depth in lesson 3 of this module.

A handoff-ready file

Organise the file so it is easy to navigate:

1. A cover or index page with the project name, status, owner, links to the ticket and research, and a changelog.
2. Ready-for-dev sections. Mark which frames are final. Figma lets you mark sections "Ready for dev"; otherwise a clear label works.
3. The flow at the top: the screens in order, with arrows, so the developer sees the journey.
4. Each screen with its states next to it: default, loading, empty, error, long content.
5. Numbered annotations beside the design, with matching notes in a margin. Avoid notes scattered over the artwork.
6. Responsive versions at the key breakpoints, or written rules.

Worked example: annotating a sign-up form

Screen: Create account (mobile, 360 wide; desktop 1280, form max-width 400, centred)

1  Email field (Input/Default from the system)
   Validate on blur: must contain @ and a domain. Error text: "Enter an email address
   like name@example.com". Do not clear the field on error.
2  Password field (Input/Password)
   Min 8 characters, show/hide toggle (accessible label "Show password").
   Strength hint updates as the user types; it never blocks submit on its own.
3  "Create account" (Button/Primary/Medium)
   Enabled at all times. On submit with errors: focus moves to the first invalid field,
   and a summary appears above the form.
   Loading: label "Creating account...", repeat clicks ignored.
4  Server error (Alert/Error, above form)
   "We couldn't create your account. Try again in a minute." Keep entered data.
5  Success -> navigate to "Check your email" screen (frame 2.3).
Long content: error text wraps; never truncate.
Tokens: spacing between fields space-4; label to input space-1.

Each note says what the design cannot. Measurements and colours come from the file or Dev Mode; there is no need to repeat them, except where a rule matters (max-width 400).

Working with engineers

• Involve them early. Review rough flows with an engineer before polishing. They will spot technical constraints and cheaper alternatives.
• Walk through the design in a short meeting at handoff rather than only sending a link.
• Agree on naming: component names and token names in Figma should match the code.
• Keep one source of truth. If a decision changes in chat, update the file and the changelog.
• Review the build. Check the implemented version against the spec (often called design QA) and file small, specific issues with screenshots.

Common mistakes

• Only the happy path. Error, empty and loading states are part of the design.
• Redlining every pixel when the tool already provides it, while forgetting behaviour.
• Unclear status. Developers build an exploration that was never final.
• Detached components in final frames, so developers cannot tell which system component to use.
• Silent changes after handoff with no changelog.
• Annotations on top of the artwork that hide the design.

Quick recap

• Handoff is a continuing conversation; specs answer questions before they are asked.
• Tools show measurements; annotations show intent: behaviour, states, edge cases, responsive and content rules.
• Organise the file with an index, ready-for-dev sections, the flow, states and numbered notes.
• Involve engineers early, match naming, keep one source of truth and review the build.

Try it

On the Do tab you will annotate one screen from your own project for engineering.