Marcus Andrey Study
Ler em português Library

UX Foundations · Step 8 · 6 min read

Handoff to developers

A design is a set of decisions, and developers can only build the ones you made visible. What to specify (states, edge cases, behaviour, spacing through tokens, accessibility notes), why working with developers early beats a big handoff at the end, and how tools like Figma Dev Mode can help.

Developers build what you decided, and guess the rest. A mock-up shows one moment: the happy screen, with a short name and perfect data. The product has to work in every other moment too: while loading, when the list is empty, when the name is 60 characters long, when someone uses only a keyboard. A good handoff answers those questions before they are asked. A better one is a conversation that started weeks earlier.

What you'll be able to do after reading:

  • List what a handoff must specify beyond the mock-up
  • Write states, edge cases and behaviour in plain words
  • Refer to spacing, colour and type through design tokens
  • Bring developers in early, so the handoff holds no surprises

1. Handoff is a conversation, not a delivery

The word "handoff" suggests throwing a file over a wall. In practice, the teams that work well talk all along. Kelley Gordon at NN/g describes the common failure: "If developers see the design only after user testing and stakeholder validation, it's already too late." She suggests treating design and development as "coowners of the product experience", and to "Establish a shared vocabulary early" (NN/g, Gordon, From Confrontation to Collaboration: The Developer-Designer Relationship, 2025).

In practice: show sketches to a developer in the first week, ask what is hard to build, and agree on names for things. By the time you "hand off", the developer has already seen the design grow.

A white-on-blue architectural floor plan from 1913, with each room labelled by name, such as Chambre, Bain and Palier, and its size in metres.
Every room has a name and its size written in, so the builder never has to guess. A good handoff does the same for an interface. Blueprint, 1913, unknown architect, Cooper Hewitt, Smithsonian Design Museum (cropped), Wikimedia Commons, public domain.

2. What to specify

1States

Empty, loading, error, success, disabled.

Not just the happy screen
2Edge cases

Long names, no data, 999+ items, offline.

What breaks the layout?
3Behaviour

What happens on tap, on hover, after saving.

Write it in words
4Tokens

Spacing, colour and type by name, not by pixel.

space-16, not "about 16"
5Access

Labels, focus order, what a screen reader says.

Decided by design, not left to code
Five things a handoff should answer, so developers don't have to guess. Diagram: Marcus Andrey, CC BY 4.0.
  • States. Every screen and component in each state it can be in: empty, loading, partial, error, success, disabled. See Interface states: empty, loading, error, success.
  • Edge cases. What happens with very long text, no data, one item, a thousand items, a slow or lost connection, a different language.
  • Behaviour. What happens on tap, on hover, on focus, after saving, after an error. Write it in words; a static screen can't show it.
  • Spacing, colour and type through tokens. Name the decision ("space-16", "text-danger") instead of measuring pixels. The W3C Design Tokens Community Group describes tokens as "a methodology for expressing design decisions in a platform-agnostic way so that they can be shared across different disciplines, tools, and technologies"; its format reached a first stable version in October 2025 (W3C DTCG, Design Tokens specification reaches first stable version, 2025).
  • Accessibility notes. Labels, heading levels, focus order, what a screen reader should announce, text alternatives for images. The W3C warns that "When accessibility is left until late in a project, the responsibility often falls on developers", who then end up "selecting colors, describing images, and writing headings" (W3C WAI, Accessibility Roles and Responsibilities Mapping, draft, updated 2026).

3. A worked example

A "Save address" form, specified in words next to the mock-up:

Topic What the spec says
States Default; saving (button shows a spinner and is disabled); saved (message "Address saved" for 4 seconds); error (message above the form, fields keep their values)
Edge cases Street names up to 120 characters wrap to two lines; postcode field accepts spaces; if offline, show "You're offline. We'll save when you reconnect."
Behaviour Validate each field when the person leaves it, not while typing; Enter submits the form
Tokens Gap between fields: space-16; error text: text-danger; labels: body-small
Accessibility Every field has a visible label; error messages are linked to their field and announced; focus moves to the first field with an error

None of this is visible in a single mock-up, and all of it is a design decision.


4. Tools help, but don't replace the spec

Design tools now have handoff features. In Figma, for example, Dev Mode is described as "a developer-focused workspace for inspecting designs, viewing properties and generated code, downloading assets, comparing changes, and managing design handoff", and designs can be marked "ready for dev" (Figma Help Center, Guide to Dev Mode). Dev Mode isn't on every plan: the help page lists Professional, Education, Organization, Government and Enterprise. Inspection shows what you drew; it can't show why, or what happens in the states you didn't draw. For writing specs that AI tools can also use, see Design specs for AI.


5. Common mistakes

  • Handing over only the happy path, with perfect data.
  • Measuring pixels by hand instead of naming tokens or components.
  • Leaving accessibility "for development".
  • Showing the design to developers for the first time at handoff.
  • Treating the handoff as the end: not checking the built version before release.

6. Vocabulary

Term Meaning
Handoff Passing a design to the people who will build it, with everything they need
Spec The written decisions behind a design: states, behaviour, rules
State One condition of a screen or component (empty, loading, error…)
Edge case An unusual situation that can break the design
Design token A named design decision, like a colour or a spacing value
Design QA Checking the built product against the design before release

7. Try it (no tools needed)

  1. Pick one screen of an app you use: a login, a search, a basket.
  2. On paper, list every state you think it has. Then try to cause each one in the real app (wrong password, no results, empty basket).
  3. Write three edge cases the designers may have missed, and what should happen in each.

Reflection questions: Which state was missing or confusing in the real app? Would a developer have known what to do there without asking?


8. If you already practise

  • Pair with one developer per project from the first sketch; NN/g suggests building a relationship with one person on the "other" team.
  • Keep a handoff checklist in your design system and review it in retros.
  • Do design QA together: sit with the developer and test the build, including keyboard and screen reader.

Checklist

Learn more

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Interface states: empty, loading, error, success · Design specs for AI · What a design system is · Accessibility fundamentals · Who does what on a product team

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close