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.

In short

A good design handoff gives developers the intent as well as the pixels: every state of every component, the edge cases with real data, rules for how the layout responds between breakpoints, tokens instead of raw values, and a short recorded walkthrough of the flow and the decisions behind it. Start the conversation with engineers before the handoff, agree on one channel for questions and changes afterwards, and review the build against the design together.

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.

Ask about cost while it is still cheap to change

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.

IncludeWhy the developer needs itWhere it usually lives
The goal and the userTo make sensible calls on details nobody specifiedOne paragraph at the top of the file or ticket
The full flow, in orderScreens in a grid hide the sequence and the entry pointsA prototype or a numbered flow
Every component stateHover, focus, disabled, loading, empty, error are all codeComponent variants or a states board
Edge cases with real dataLong text, zero and many items, missing images break layoutsAn edge-case frame next to each screen
Responsive rulesDevelopers build the space between your breakpoints tooAnnotations plus frames at key widths
Tokens, not raw valuesSo colours, spacing and type map to the existing systemVariables or styles in the design tool
Copy, final or flaggedPlaceholder text hides wrapping and tone problemsIn the frames, with drafts clearly marked
Motion and interaction detailsDurations, easing, what triggers whatAnnotations or a short recording
Accessibility notesFocus order, labels, what a screen reader announcesAnnotations on the relevant frames
A recorded walkthroughExplains intent and decisions that frames cannotA link in the ticket
Decision logAnswers "why is it like this?" without a meetingPinned in the file or the project channel

Try VeoRec free: 7 days of Pro free, no card, then 10 videos, 10-min recordings, AI transcripts

Add to Chrome

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.

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.

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.

Example: the edge-case frame for a team member card

Long name:

No photo:

Pending invite:

Deactivated:

More than 50 members:

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.

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.

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.

Try VeoRec free: 7 days of Pro free, no card, then 10 videos, 10-min recordings, AI transcripts

Add to Chrome

Frequently asked questions

What is design handoff?

Design handoff is the point where a designer passes a finished design to developers to build. A good handoff includes not only the screens but the states, edge cases, responsive rules, tokens, copy and the reasoning behind decisions, plus an agreed way to handle questions and changes.

What should be included in a design handoff?

At minimum: the goal, the full flow in order, every component state, edge cases with realistic data, responsive rules, design tokens, final or flagged copy, interaction and accessibility notes, and a short walkthrough of the decisions. A decision log helps engineers understand why things look the way they do.

How do designers hand off designs to developers in Figma?

Many teams use Figma's Dev Mode, where developers inspect properties, read annotations, download assets and compare versions, and designers mark work as Ready for dev. Check Figma's help pages for current plan and seat requirements. A recorded walkthrough and written rules still cover what the inspect panel cannot.

How do you hand off responsive designs?

Provide frames at the key breakpoints and write rules for what happens between them: what reflows, what moves or hides, minimum and maximum widths, and touch differences. Developers build every width, so rules prevent guesses at sizes you did not draw.

Should designers be involved after handoff?

Yes. Questions come up during the build and designs change. Agree on one channel for questions, announce changes explicitly, and review the built version on staging and a real device before the work is marked done.