Design handoff to developers: what to include so nothing is guessed

Developers rarely build the wrong thing on purpose. They build what the file shows, and most files only show the happy path at one screen size.

By the VeoRec team · Oct 3, 2026 · 11 min read

A design handoff is the moment a design stops being the designer's problem and becomes the developer's. That is also why it so often goes wrong. The file looks finished, the developer starts building, and three days later a message arrives: "What happens when the name is too long?" or "Is this a modal on mobile too?" Each question costs a round trip, and each one the developer answers alone is a small guess baked into the product.

You cannot remove every question, and you should not try; some only appear once real data hits the layout. What you can remove is the guessing on the questions you could have answered in advance. That comes down to what you prepare, how you describe behaviour a static frame cannot show, and how the design and the build stay in step after everyone has left the handoff meeting.

Start the design handoff before the design is finished

The best handoffs are barely handoffs at all. An engineer who saw the early concepts, flagged that the live search needs an endpoint that does not exist, and suggested a cheaper pattern, will build the final design faster and with fewer surprises than one who first sees it complete.

You do not need a formal process for this. Share the flow at mid-fidelity and ask one engineer two questions: "Is anything here much harder than it looks?" and "Do we already have components for this?" Ten minutes of their time at this stage is far cheaper than discovering the same problem in the middle of the sprint.

What a complete handoff package contains

Every team's package looks a little different, but the gaps are almost always in the same places. Use this table to check yours.

This is not a call for a fifty-page spec. Most of these items are a frame, a line of annotation or a link. The aim is that a developer who opens the file on a Monday morning, with you on holiday, can build the feature without inventing anything important. If you are unsure whether something needs documenting, ask yourself whether two different developers would build it the same way from what is on the page. If not, write a sentence.

Clean up before you share. Move explorations and rejected versions to a separate, clearly named page, so nobody builds from the wrong frame. Remove hidden layers that are not meant to ship. Name frames by screen and state ("Checkout / Payment / Error") rather than "Frame 1247".

Draw every state, not just the happy one

Designs are usually reviewed in their best state: logged in, data loaded, nothing wrong. But every interactive element has several states, and each one is something a developer has to implement. If you do not draw it, they will invent it, usually by copying whatever the nearest existing component does.

• Interactive states: default, hover, pressed, focus, disabled, selected.
• Data states: loading (and what loads first), empty for a new user, empty after filtering, partial, error, success.
• Form states: untouched, typing, invalid with the message, valid, submitting, submitted.
• Permission states: what a viewer sees compared with an admin, and what a locked feature looks like.

Focus deserves a special mention because it is the state most often left out of mockups. The W3C's Focus Visible criterion requires that keyboard users can see which element has focus. If your design does not show a focus style, the build either ships the browser default or none at all. Draw it once in the component and it carries everywhere.

Design the edge cases with real data

Lorem ipsum and perfectly sized names are kind to layouts in a way real content never is. Before handoff, put real or realistic data into the key screens and see what breaks.

• The longest plausible name, title or email address. Does it wrap, truncate with an ellipsis, or push the button off the card?
• Zero items, one item, and a few hundred. Does pagination appear, does the empty state make sense?
• Missing data: no avatar, no price, no description. What fills the gap?
• Numbers at their extremes: a price of 0, a price of 1,249,000, a negative balance.
• Translated text, if the product is localised. German and Finnish strings are often much longer than English; some languages read right to left.
• Slow or failed requests. What does the person see after five seconds, and after a timeout?

You do not need a polished frame for each one. A single "edge cases" frame beside the main screen, with short annotations, tells the developer you have thought about it and what you want to happen.

That is five lines of text and maybe one extra frame. Without it, the developer makes five decisions alone, and at least one of them (the silhouette, the sort order, the missing search) comes back to you as a bug after release.

Describe responsive behaviour as rules

Three frames (mobile, tablet, desktop) show three points on a continuous range. The developer has to build every width in between, and plenty of responsive bugs live there: a card grid at 900 pixels, a navigation bar just before it collapses, a table on a small laptop.

Add a few sentences of rules next to the frames. They are quicker to write than extra mockups and more useful to the person implementing them.

1. Say what reflows "The three pricing cards sit in a row above 960px, stack below it. The recommended card moves to the top when stacked."
2. Say what changes or hides "Below 720px the secondary navigation moves into the menu. The comparison table becomes a list per plan."
3. Give limits "Content max width 1200px, centred. Cards never narrower than 280px. Body text never smaller than 16px."
4. Note touch differences "Hover previews become a tap on mobile. Tap targets at least 44 by 44."

During review you can approximate other screen sizes with the device toolbar in Chrome DevTools. Google's own Device Mode documentation calls it a first-order approximation, so check the final build on at least one real phone too.

Annotate the behaviour a frame cannot show

A mockup is a photograph of one moment. Much of what makes an interface feel right happens between moments, and developers cannot inspect it. Write it down, briefly, on the frame where it applies.

• Motion: what animates, how long it takes and how it eases. "Drawer slides in from the right, about 200ms, ease-out; the page behind dims." If you prototyped it, say which prototype frame shows it.
• Triggers: what starts each change. On click, on hover, after a delay, when the API responds, when the user scrolls past a point.
• Content rules: character limits, what truncates and where, whether a field accepts emoji or line breaks, how numbers and dates are formatted.
• Persistence: what is remembered. Does the filter survive a reload? Does a dismissed banner come back next week?
• Focus and keyboard: where focus goes when a dialog opens and closes, what Escape does, the tab order through a complex form.

None of these need essays. A line each is enough, and it stops the developer from choosing a 600ms bounce because the component library defaulted to it.

Specs, tokens and the design tool's handoff features

Developers need numbers, but raw numbers are a trap. "#2F6BFF, 14px, 600" invites the developer to hard-code a value that should have been the existing primary colour and the existing label style. Use your design system's variables and styles, and name layers and components so they match what is in the codebase. When something is genuinely new, say so explicitly.

Most design tools now have a handoff view. In Figma it is called Dev Mode: developers inspect measurements and properties, get code snippets, read designers' annotations, download assets and compare versions of a frame. Designers can mark sections, frames and components as Ready for dev, and Figma flags them as changed if they are edited afterwards. According to Figma's Dev Mode guide and its page on statuses and notifications, at the time of writing Dev Mode is on paid plans and needs a Full or Dev seat, and some status features are limited to the Organization and Enterprise plans.

Figma tutorial: Collaboration and handoff in Dev Mode (video, Figma)

Whatever the tool, the inspect panel answers "how big?" and "what colour?". It does not answer "why?", "what happens next?" or "what if?". That is what the next part is for.

Record a walkthrough of the flow and the decisions

A short recording is the fastest way to transfer the parts of a design that static frames cannot carry: the sequence, the interactions, and the reasoning. Engineers can rewatch it when they reach a tricky screen, and new teammates can catch up months later without a meeting.

Keep it to the flow you are handing off and record it in this order: the goal in a sentence, the path through the prototype, the interactions that need care, the edge cases and states, then the open questions. Point at things with the cursor as you talk. Add a chapter marker at each part so the engineer can jump back to "empty state" in two weeks. VeoRec's markers are a keypress (M) while recording, and every recording gets a transcript, which makes "what did she say about the error message?" a search instead of a rewatch.

Link the recording in the ticket, next to the file, not in a chat thread where it will scroll away. For the broader version of this habit, see developer handoff documentation, and for the recording itself, how to record a Figma walkthrough.

Run a short handoff meeting where the developer drives

Even with a recording, a short live session at the start of the build is worth it, especially for larger features. The trick is to flip the usual roles: instead of the designer presenting for the third time, the developer who will build it shares the screen and walks through the design as they understand it.

Misunderstandings surface immediately. "So this list loads all items at once?" "No, 20 at a time, the rest on scroll." That exchange takes ten seconds in a meeting and a day if it is discovered in code review. Keep the session to about half an hour and end it with three things written down in the ticket:

1. The open questions, each with an owner and a date.
2. Anything the developer flagged as expensive, and what was agreed instead.
3. What "done" means for this ticket: which states, which breakpoints, which browsers.

Developers who prefer async can do the same thing in a recording of their own: a two-minute "here is how I read this design" video that the designer watches and comments on. Recording tools built for engineers, like VeoRec, a screen recorder for developers, make that quick: the share link is already copied when you stop recording.

Agree how questions and changes travel afterwards

No handoff is complete. Questions will come up, and designs will change after the developer has started. The damage comes from both travelling through random channels: a question answered in a direct message that nobody else sees, a frame quietly edited after the developer copied its values.

• One place for questions. The ticket, a thread on the file, or a dedicated channel. Answers go there too, so the next person finds them.
• Announce changes explicitly. If you edit a frame after handoff, say what changed and why, in the same place. Status features that mark a design as changed help, but a sentence of explanation is what people act on.
• Version the big ones. If the change is more than a tweak, duplicate the frame and label it, rather than editing the one the developer is building from.
• Agree who decides small things. Let developers make obvious calls (a 2px alignment, a missing hover) without asking, and say which kinds of questions you want to hear about.

Review the build against the design together

Handoff ends when the built version matches the intent, not when the file is shared. Plan a design review of the build, ideally on the staging site and on a real phone, before the ticket is closed.

Give that feedback the same care you gave the design: exact location, state, screen width, and what you expected. A recording of you clicking through the staging build while you talk is often clearer than a list of screenshots. When a web page is recorded as a Chrome tab in VeoRec, notes can stay attached to the page elements, so a note on the pricing card points at that card rather than at a fixed spot on the frame that happened to hold it.

Sort what you find into must-fix before release and follow-up tickets, and resolve each note as it is fixed. For the mechanics of collecting notes on a live page, see website feedback; for the QA side of the same loop, the QA to developer handoff post has a checklist.

The handoff is finished when the build matches the intent, not when the file link is sent.

What to do next

Pick the next feature you will hand off and work through the checklist above before the handoff meeting, not after. The two items most teams skip are the edge-case frame and the written responsive rules; do those first. Then record a short walkthrough with chapters, link it in the ticket, and book a review of the staging build before the work is called done.

After the feature ships, ask the developer one question: "What did you have to guess?" Whatever they name is the item to add to your own checklist for next time. Handoffs improve fastest when the person receiving them tells you where they fell short, and most developers are glad to be asked.