How to Hand Off a Design a Developer Can Build

A design file that leaves Figma and lands in a codebase is a translation, and translations lose things. The best handoff is not a prettier mockup or a longer spec document. It is a deliberate act of subtraction: removing every question a developer would otherwise have to answer alone at 4 p.m. on a Thursday, three tickets deep, guessing whether the button sits 12 pixels or 16 from the card edge.

Most handoff advice treats the problem as one of completeness. Export every frame, annotate every state, attach every asset. The result is often a 40-page spec that nobody reads and a Slack thread full of "what happens when the name is long?" The real skill is deciding what the developer genuinely needs and what is noise dressed up as thoroughness.

The screenshot is not the design

A static frame shows one frozen moment: the happy path, a name of average length, an image that loaded, a screen wide enough. A developer builds a system that has to survive the unhappy paths. Handing over only the frozen moment guarantees rework.

The fix is cheap. Before the handoff meeting, the designer stress-tests their own frame. Swap the name for a 40-character one. Turn the avatar into a broken image. Shrink the viewport to the narrowest supported width. Set the count to zero. Each of these becomes a small annotated note beside the main frame: here is what collapses, here is what wraps, here is what disappears entirely.

A developer who sees the empty state, the error state, and the long-content state on day one builds for them from the start. A developer who discovers them on day nine rebuilds half a component. The cost of those extra annotations is maybe twenty minutes; the cost of skipping them is measured in days.

Spacing that survives a reflow

Pixel measurements in a spec are a trap. A note that says "24px between the title and the body" tells the developer almost nothing about intent. Is 24 sacred, or is it a byproduct of this particular font size? Does it scale on a tablet? Does it collapse when the title wraps to two lines?

What actually transfers is the relationship between values. The gap between sections is double the gap between related fields. The card padding matches the page gutter. The button sits flush with the text column, not with the card. Those are rules, and rules can be encoded in spacing tokens or CSS variables. A single number cannot.

Designers who care about this hand off a small spacing scale, four or five steps, and mark which step each gap belongs to. Developers who receive that scale can rebuild the layout with confidence even when the content shifts. The mockup becomes an example of the system rather than a photocopy of it.

Naming the states no one drew

Every interactive element has a hidden life. A button is hovered, pressed, focused, disabled, loading. A form field is empty, filled, invalid, submitting. A list is loading, empty, partially loaded, errored. Design tools make it easy to draw only the resting state and call it done.

The handoff should include a compact state matrix for each interactive component: what it looks like, what triggers the change, and what the user can do in each state. A disabled button that offers no explanation is a support ticket waiting to happen. A loading state with no timeout rule is a spinner that never stops.

This is where the designer earns their keep. The developer can implement any visual state that gets described. What they cannot do is invent the product logic behind it. When the loading spinner gives up and shows an error, that is a decision. Make it in the design, not in the pull request review.

The typography handoff is a scale, not a font

Sending over a font file and a screenshot of headings is not a typography handoff. The developer needs to know the scale: which sizes exist, which weights pair with which sizes, how line height changes between display text and body copy, and what happens when a heading runs to three lines on mobile.

Most of this can be captured in a short table. Six rows, one per text style, with size, weight, line height, and a note on where it is used. That table is more valuable than any amount of annotation on individual frames, because it tells the developer how to build new text combinations the designer never drew.

The trap here is responsive type. A 48-pixel headline on desktop that stays 48 on a phone will look absurd or overflow. If the design intends the headline to step down, that intent has to be written down, with the breakpoint and the target size. Developers are not mind readers, and the browser will not guess.

Assets arrive with their constraints attached

An exported icon is a file. A usable icon is a file plus rules: how it scales, whether it inherits color, what its minimum tap target is, whether it aligns optically or metrically with adjacent text. Handing over a folder of SVGs without those rules guarantees a codebase full of one-off fixes.

The same logic applies to images. The designer knows the intended crop, the aspect ratio, and roughly how much the subject can be cut off before the composition falls apart. That knowledge belongs in the handoff. A developer who receives a 3000-pixel photo and no crop guidance will either ship a distorted image or spend an afternoon guessing.

Naming matters more than designers admit. A file called "hero-final-v3" is a future mystery. A file called "hero-dashboard-16x9" tells the developer what it is and where it goes. Ten seconds of renaming saves ten minutes of questions later, and the questions compound across a project.

What the developer should not have to ask

A useful test before handoff: read the spec as if seeing it for the first time and list every question it does not answer. What is the maximum length of this input? Does this tooltip appear on hover only, or on focus too? What happens to the layout when the sidebar collapses? Does the animation run on every load, or only the first?

Each unanswered question becomes a decision the developer makes alone, often late at night, often wrong. Some of those decisions are trivial and get fixed in review. Others quietly become product behavior that nobody intended, and by the time anyone notices, the workaround is baked into three other screens.

The discipline is to answer the questions in writing before the meeting, not during it. A short list of decisions, dated and named, is worth more than a polished presentation. The presentation impresses once. The list gets consulted for the life of the feature.

The handoff meeting is for disagreement, not delivery

If the handoff meeting is the first time the developer sees the design, the meeting will be spent on discovery rather than on the things that actually matter. The better pattern is to send the spec ahead, let the developer read it, and use the meeting to surface the places where the design is expensive, ambiguous, or impossible within the current architecture.

Those conversations are the most valuable part of the whole process. A developer who says "this interaction needs a state machine we do not have" is giving the designer a chance to simplify before the work begins. A designer who says "this component is reused on four screens, so the padding has to be flexible" is saving the developer from a fragile build.

The meeting should end with a short list of agreed changes, not a vague sense that everyone is aligned. Ambiguity that survives the meeting becomes ambiguity in the code, and code has a way of making ambiguous decisions permanent.

When the build comes back different

It always comes back different. A shadow is off by a shade, the spacing tightened somewhere, a hover state got skipped. The instinct is to file a bug for every deviation. The better move is to sort the differences into two piles: things that are wrong, and things that were never specified.

The second pile is the designer's homework. If a deviation happened because the spec was silent, the spec was the problem, and the fix belongs in the handoff for the next feature. A team that treats every mismatch as a developer error never improves its handoffs. A team that treats mismatches as feedback on the spec gets better every sprint.

The best handoff is the one the developer barely remembers, because nothing went wrong. No frantic Slack messages, no guessing at spacing, no surprise states discovered in QA. That quiet is the goal, and it is built out of unglamorous things: a state matrix, a spacing scale, a type table, a folder of properly named assets, and a short list of decisions written down before anyone opened a code editor.