Design handoff: the specification was never the problem
By Allan Leone on
A decade of tools promised to fix design-to-development handoff, and they largely did fix the file transfer. Builds still come back wrong, because the thing that was missing was never in the file.
Handoff tooling is genuinely good now. Specifications are exact, tokens export cleanly, and an engineer can pull real values in seconds without asking anyone. The problem the tools set out to solve is solved.
Builds still come back wrong. Not because someone misread a margin, but because the file described one state of a system that has dozens.
What was never in the mockup
- What happens when that name is eighty characters long, or two characters long.
- What the list looks like empty, and with ten thousand rows.
- Which of these two things wins when both conditions are true at once.
- What the user sees while it loads, and what they see when it fails.
- Whether the action is reversible, and what undo means if it is.
That information existed. It lived in the designer's head and it transferred by proximity: a conversation, a Slack thread, someone leaning over a desk at the right moment. The mockup was never the specification. It was a prompt for a conversation that happened around it.
Why this is getting worse
Two things changed at once. Distributed teams removed a lot of the proximity, and now agents are consuming the specification too.
An engineer who receives an underspecified design asks a question or makes a judgement call informed by knowing the product. An agent does neither. It picks something plausible and implements it consistently, which means the gap in the spec becomes a pattern in the codebase rather than a single bug.
The artefact that fixes it
Not a longer document. A short list attached to each screen covering the states that are not drawn: empty, loading, error, maximum content, minimum content, and what is irreversible.
Six lines per screen. It takes about ten minutes and it is the part of the handoff that was always doing the real work, just informally.
Where to start
- Add the six-state list to the next screen you hand over. Empty, loading, error, max content, min content, irreversible actions.
- Look at the last three build discrepancies your team had. Ask whether the information was in the file or in someone's head.
- Put the edge cases in the same place as the design, not in a separate document nobody opens.
- If agents are writing your components, treat the states list as required rather than optional. It is now the difference between one wrong screen and forty.
Tags: process, design-systems, engineering