Design Handoff to Developer: How Freelancers Get Builds That Match the Design
A good design handoff gives the developer three things: the design files with real access (not a screenshot), a written spec covering the states and edge cases the mockup doesn't show, and one agreed channel for questions and QA feedback. If you hand off all three, the build will look like your design. If you hand off a Figma link and a "let me know if you have questions", it won't.
That gap between what you designed and what got built is rarely the developer's fault. It's a handoff problem, and it's fixable with about two hours of structured work per project.
Why builds drift from designs
If you've worked with developers before, you know the moment. The staging link arrives, you open it, and something is off. The spacing is tighter than your file. The hover states are missing. The font renders heavier than in Figma. The mobile layout does something you never designed because you never designed a mobile layout for that section, and the developer had to improvise.
Here's how it usually plays out for a freelance designer:
You finish the design, the client approves it, and you send the developer a Figma link. Two weeks later you get a staging URL. You spot 30 differences. You write them up in a long email: "the hero padding is off, the button radius is wrong, the testimonial cards stack weirdly on tablet." The developer fixes half of them, misinterprets a quarter, and pushes back on the rest because "that's how it came from the file." Three more rounds of emails follow. The client is waiting. Nobody is happy, and the relationship you need for the next project is fraying.
None of this happened because anyone was careless. It happened because a static mockup answers maybe 60% of the questions a developer has to answer to build a page. The other 40% (hover states, loading states, error states, breakpoint behavior, what happens when the headline is twice as long) got answered by whoever was sitting at the keyboard when the question came up. That was the developer, not you.
The handoff is where you close that 40% gap before the build starts, instead of during QA when every fix costs a round trip.
The handoff process, step by step
- Clean your design file before sharing it. Delete abandoned explorations, name your frames properly ("Home / Desktop", "Home / Mobile", not "Frame 847"), and put final screens on one clearly labeled page. A developer who has to guess which of four similar homepages is the real one will guess wrong at least once.
- Design the states, not just the happy path. Every interactive element needs hover, focus, active, and disabled states. Every form needs an error state and a success state. Every list or grid needs an empty state. If you skip these, the developer invents them, and their version of "invented" is usually browser defaults.
- Cover the breakpoints that matter. You don't need six artboards per screen, but you need desktop and mobile at minimum, plus a note on how in-between widths should behave ("the three cards wrap to one column below 768px"). Undesigned breakpoints are the single biggest source of "that's not what I meant" in freelance projects.
- Write a one-page spec for what the file can't show. Animations and transitions ("fade in over 200ms", "menu slides from the right"), link destinations, third-party embeds, form handling (where do submissions go?), and any CMS requirements ("the client will edit these testimonials, so they need to be a collection"). Bullet points are fine. This takes 30 minutes and saves days.
- Hand off assets in the formats developers actually need. Export logos and icons as SVG, photos as optimized JPG or WebP, and confirm font licensing for web use. "It's all in the Figma" is technically true and practically annoying; developers can export from Figma, but a tidy asset folder removes one more source of friction and mistakes.
- Do a 30-minute walkthrough call. Screen-share the design and talk through it. Point out what's intentional ("this asymmetry is deliberate") and what's flexible ("if the exact easing is a pain, approximate it"). Most build mistakes that survive to QA were questions the developer decided not to ask over email. On a call, they ask.
- Agree on the QA process before the build starts. Decide now: where does staging feedback go, in what format, and how many QA rounds are included? A developer who knows QA comes as pinned, numbered comments on the staging site will plan for it. One who gets a surprise 40-item email three days before launch will resent it.
- Review the staging site visually, in the browser, at real sizes. When the build is ready, don't skim it on your laptop and call it done. Check it at mobile width, tablet width, and a large desktop. Compare against the file side by side. This is your design QA pass, and it's the step where a visual feedback tool earns its keep.
What developers actually complain about
It's worth knowing what the other side of the handoff looks like, because most designers have never heard it directly.
Developers' most common complaints about designer handoffs are remarkably consistent: files with no organization, missing states ("what does this dropdown look like open?"), no mobile designs, spacing values that are visibly inconsistent between screens (16px here, 17px there, 15px there, clearly all meant to be the same), and feedback that arrives as vague prose ("the header feels off") instead of something they can act on.
Notice that almost none of these are about design quality. Developers don't complain that your typography choices are wrong. They complain that they can't tell what you intended. Every ambiguity in your handoff becomes a decision the developer has to make alone, usually under time pressure, usually without your eye for the details you care about.
The flip side: a designer who hands off organized files, complete states, and precise feedback becomes the designer developers want to work with again. For a freelancer, being easy to build for is a referral engine. Developers recommend designers to their clients constantly.
Design QA: the step most freelancers skip
Handoff isn't finished when you send the files. It's finished when the live build matches the design, and the only way to get there is a structured design QA pass on the staging site.
Unstructured QA looks like this: you scroll through staging, notice things, and describe them in an email or WhatsApp message. "The spacing under the hero is too big on mobile." Which spacing? How much too big? On which device? The developer opens the site on their phone, sees something slightly different (different device, different browser), makes their best guess, and pushes a fix that may or may not be what you meant. Multiply by 30 issues and two or three rounds, and QA eats a week.
Structured QA looks like this: you go through the staging site once, systematically, and leave each issue as a pinned comment on the exact element it concerns, with the expected value ("padding should be 48px, matches Figma frame Home/Mobile"). The developer gets a numbered list where every item has a location, a description, and a target. No interpretation required. Most items get fixed in one pass.
This is exactly the workflow dotts was built for. You share the staging URL through dotts, click directly on the element that's wrong, and type the comment. The pin sits on the element itself, and dotts automatically captures your browser, device, and screen size with each comment, which matters enormously for responsive bugs; "looks broken on mobile" becomes "looks broken on Safari, iPhone 13, 390px wide" without you typing any of it. The developer doesn't need an account to view and respond, and neither does the client if you want them in the loop for final review.
It also solves the QA problem in the other direction. When the client reviews the staging site, their feedback lands as pins in the same place, instead of a separate WhatsApp thread you have to translate and forward to the developer.
Pricing the handoff into your projects
A proper handoff (states, breakpoints, spec, walkthrough, QA pass) takes real time: typically four to eight hours on a normal site project. Freelancers routinely do this work without charging for it, squeezing it into the gap between "design approved" and "final invoice."
Stop doing that. Handoff and design QA are line items. Something like "Developer handoff and design QA: preparation of development-ready files, specification document, handoff call, and two rounds of staging review" belongs in your proposal, priced accordingly. Clients accept it without blinking, because the alternative (a build that doesn't match the design they approved) is precisely what they're paying you to prevent.
There's a positioning benefit too. A designer who has a named, structured handoff process reads as more senior than one who "sends over the files." It's one of the cheapest ways to justify higher rates, because it costs you a checklist, not a new skill.
A real-world example
Jonas is a freelance web designer in Hamburg. Last year he designed a site for a logistics company; an external developer built it in Webflow. Jonas sent the Figma link, the developer built for two weeks, and then QA happened over email. It took 11 days, four rounds, and 63 messages. Two bugs Jonas had reported in round one were still live at launch because they got buried mid-thread. The developer later told him, politely, that the project had been "a lot of back and forth."
On the next project, Jonas changed three things. He designed mobile versions and interaction states before handoff. He wrote a one-page spec and walked the developer through it on a 25-minute call. And he did his staging QA through dotts: one systematic pass, 28 pinned comments, each with the expected value from the design file.
The developer resolved 26 of the 28 in the first fix round; the remaining two were genuine discussion points, not misunderstandings. QA took three days instead of eleven. Same designer, same skill level. The difference was the handoff.
The bottom line
Builds don't drift from designs because developers are sloppy; they drift because static mockups leave 40% of the decisions unspecified, and someone else fills the gap. Close it with complete states, defined breakpoints, a one-page spec, a walkthrough call, and one structured design QA pass on staging. It's a few hours of work that turns your riskiest project phase into a routine one.
FAQ
What should a design handoff to a developer include?
Five things: organized design files with named frames, all interactive states (hover, focus, error, empty, loading), designs or rules for each breakpoint, a short written spec for behavior the file can't show (animations, links, form handling, CMS needs), and exported assets in web-ready formats. A 30-minute walkthrough call ties it together.
Do I need to design every breakpoint?
No. Desktop and mobile designs plus written rules for in-between widths cover most projects. The rule matters more than the artboard: "cards wrap to one column below 768px" prevents more bugs than a third set of mockups.
How do developers prefer to receive design feedback during QA?
As specific, located, actionable items, not prose. A pinned comment on the exact element with the expected value ("radius should be 8px") beats "the buttons look off" every time. A design handoff to a developer really ends at QA, so pick a tool that pins feedback to elements; dotts does this on live staging sites and captures browser and device data automatically.
Should the client be involved in the developer handoff?
Not in the handoff itself; that's a conversation between you and the developer. But the client should review the staging site before launch, and it saves you translation work if their feedback lands in the same tool and format as yours.
What's the difference between design handoff and design QA?
Handoff happens before the build: files, spec, assets, walkthrough. Design QA happens after: you compare the staging site against the design and report differences. They're two ends of the same responsibility, making sure what ships matches what was approved.
Who is responsible when the build doesn't match the design?
Practically, whoever left the ambiguity. If you never designed the tablet layout, the developer's improvisation isn't a bug. If you specified 48px and got 32px, it is. This is why a written spec protects both sides: it turns arguments into lookups.
Can I charge for handoff and design QA as a freelancer?
Yes, and you should. Four to eight hours of real work deserves a line item in the proposal. Frame it as insurance on the design investment: "developer handoff and design QA, including two rounds of staging review."
What tools do I need for a design handoff?
Less than you'd think. Figma's inspect features handle measurements and exports. A shared doc covers the spec. For the QA half, use a visual feedback tool like dotts so staging feedback is pinned to elements instead of scattered across email; your developer will thank you, and nothing gets lost mid-thread.
Your next handoff doesn't need to end in a 63-email thread. Try dotts free →
Further reading
Start Collecting Feedback in Seconds with dotts
Forget messy email threads and unclear revision requests. dotts makes feedback fast, clear, and organized so you can focus on what matters—getting work done.