# Why a design file is not a handoff

By Bart Dunweg, Jan 21, 2025 · 8 min read

Design handoff, the moment a design passes from designer to developer, keeps getting better tools. What goes missing is the reasoning behind the design, and a more detailed file does not carry that.

Design handoff is the moment a design passes from the designer to the developers who build it. The tools for it keep changing. Drawings marked up with measurements became detailed specifications, specifications became design files you could click on to read every value, and those became code generated straight from the design. Each was an improvement, and none of them fixed what it was meant to fix.

The problem was never the format. Files have steadily improved and the friction between designers and developers has stayed, which suggests the friction is not in the file.

## What a design file leaves out

A design file is a set of decisions with the reasoning removed. It shows sixteen pixels of space but not that sixteen was chosen because twenty-four broke the layout on the smallest phone. It shows what a screen looks like with nothing in it yet, but not that this version matters more than the full one, because most accounts will never fill it.

When an engineer builds from a file, they are working out the intent from what is on the page, and they are doing it while dealing with constraints the designer may not have known about. Most disagreements about how something was built are not really disagreements. They are two people making reasonable guesses from incomplete information about each other's problem.

A more detailed file does not fix this. It adds information about what the design looks like, which helps a little, and it does nothing about the reasoning, which is where the value was.

### The questions that never get asked

The clearest sign is the question an engineer decides not to ask. Something in the design does not quite work with how the information arrives, and it would take a conversation to sort out, and the designer is in another timezone or another project or simply hard to interrupt. So a reasonable guess gets made.

That guess ships. It is usually fine. Occasionally it is the thing that makes the feature worse than it should have been, and nobody ever finds out, because the guess was never raised as a decision.

Multiply that by every screen in a release and you have the real cost of relying on handoff, which is not rework. It is a long list of small choices nobody looked at.

## What has worked instead

This is not a formal process. It is a set of habits that consistently reduced how much a handoff had to carry.

### Bring the engineer in before the design is good

Not at the review, but at the point where there are three sketches and no decision. The constraints that matter come up in that conversation, and they come up cheaply. An engineer who saw the alternatives understands the choice, and an engineer who understands the choice can adapt it correctly when something unexpected comes up.

### Design the states you cannot see

Loading, empty, an error, text that is too long, no connection, half-finished. These are the situations where what gets built differs most from what was meant, because they are where the file is usually silent and the engineer has to invent. Every one you specify is a guess you have prevented.

### Write down the why for anything non-obvious

Not a document. A sentence next to the screen in the design file. "Sixteen, because twenty-four breaks the line on the smallest phone." It takes ten seconds and it stays after you leave the project, which the reasoning in your head does not.

Write what a conversation cannot carry: the constraint that made an obvious approach wrong, the thing that must not change even if everything around it does. Skip what a reusable part already settles and what the screen visibly shows. The test is whether the note would still help somebody in six months who was not there. Reasoning passes that test. Measurements do not.

### Review the built thing together, on a real device, early

Not to catch mistakes, though you will. To rebuild shared understanding while it is still cheap to change something. A ten minute call at fifty percent done is worth more than an hour of comments at ninety-five.

### Asking costs more on one side

A designer interrupting an engineer costs the engineer a chunk of focus, and
everybody knows it. An engineer interrupting a designer costs roughly the same
and nobody counts it, because design work is assumed to be interruptible.

The result is that the cheapest move for either side is to guess rather than
ask, and the guesses stay invisible until they ship. Teams that work well have
usually made asking cheap in some specific way: a channel where a half-formed
question is normal, a standing fifteen minutes nobody has to book, a habit of
answering in a thread rather than a meeting.

These are not a process. They are small agreements that make asking easier,
and that does more for the quality of what gets built than any specification
format has.

## How finished a design should be depends on the people

A recurring argument is how finished a design should be before it is handed over. Designers call this fidelity. In practice it depends on the two people involved, and treating it as one fixed standard is why the argument keeps coming back.

An engineer who has worked with you for two years and knows the system needs a sketch and a conversation. A contractor joining for six weeks on code they have never seen needs something much closer to complete, because they have no background to fill the gaps with and no working relationship that makes asking easy.

Teams get into trouble by setting one standard for both. Either the experienced pair is slowed down by formalities that add nothing, or the new person is handed a sketch and left to guess, and their guesses are worse because they are new. Neither is a fidelity problem. In both cases the level of detail should have followed how much the two people already share.

### When review turns into fault-finding

There is a version of this that looks collaborative and is not: the designer
reviews every build and files every difference as a mistake.

It is tiring, it sets the two sides against each other, and it puts effort in
the wrong place. Most of what turns up in that review is a two pixel difference
nobody outside the team will ever see, and the time spent on it is time not
spent on the one screen that genuinely came out confusing.

The version that works is to be specific about what actually matters on a given
feature, and say so up front. Sometimes it is the spacing, because the
feature is a dense table. Sometimes spacing is irrelevant and the whole thing
rests on what the screen says when there is nothing in it yet. An engineer told
which aspect matters will protect it; an engineer handed a list of forty
comments will work through them in order and run out of time before the
important ones.

## The design system changes the shape of this

This is where a design system, a library of shared, reusable parts, is most useful, and it is not the reason usually given for having one.

The common argument is consistency. The better argument is that a shared system removes most of what has to be handed over at all. If a button is a component both people already understand, nobody has to specify it, inspect it, or discuss it. The conversation moves up to what the screen is trying to do, which is the conversation worth having.

It follows that poor coverage, a system that lacks many of the parts teams need, makes handoff worse, not better: every screen becomes an unmarked mix of shared parts that need no explanation and one-offs that need a lot, and telling them apart takes exactly the question the engineer was avoiding. It is the same [coverage problem that makes many design systems fail](https://bartdunweg.com/articles/on-design-systems).

## Remote teams need this too

The obvious objection is that everything above assumes people work close together, and plenty of teams do not. That is fair. But the answer to distance is not a better document, which is the same assumption as before.

The answer is to make the reasoning lasting and easy to find, because a conversation across timezones cannot be spontaneous. A short recorded walkthrough of a flow, three minutes, talking through why rather than what, is worth more than any amount of annotation. It can be watched at the point of building, which is when the questions actually come up, rather than at a review that happened before they did.

The same goes for decisions. A thread where the trade-off was argued out is more useful six months later than a tidy summary, because the summary has the alternatives removed, and the alternatives are what someone needs when the constraint changes.

## The thing to stop doing

Stop treating the moment of handoff as the point where responsibility transfers. That view causes most of the trouble. It creates a before and an after, it puts a document at the boundary, and it makes the document responsible for carrying everything that was in two people's heads.

The feature is not designed when the file is done. It is designed when it is in front of people and working, and everything between those two points is design work whether or not it happens in a design tool. Teams that work this way still have some friction while building, but they handle it in conversation, which is where it belongs.