A design handoff that doesn't bounce back

A design gets approved. It goes to engineering. Three days later there are eleven questions in a thread, half the build is blocked, and someone is asking whether the designer is still available. The design was not bad. The handoff was incomplete, and incompleteness only becomes visible downstream.

Having been on both ends of this many times, the pattern is consistent: handoffs fail on the states nobody drew, not on the screens everybody reviewed.

The screens get reviewed. The states don't.

A client approves a dashboard. What they approved was the dashboard with four cards of plausible data and a name that fits on one line. What engineering needs is everything that happens around that:

• Empty — the first run, before any data exists
• Loading — and whether that means a spinner, a skeleton, or nothing at all
• Error — what the user sees and what they can do next
• Overflow — the name that is forty characters, the list with two hundred rows
• Permissions — what a user who cannot do this thing sees instead

Each one is a decision. If the design does not make it, engineering will, usually at speed and without the context the designer had. That is how a polished comp becomes a build that feels subtly wrong in ways nobody can point at.

Tokens before screens

The second recurring failure is a file where every value is hand-placed. Spacing that is 14 here and 16 there. Four greys that are almost the same grey. A heading that is semibold on one screen and bold on the next because two people worked on it.

Engineering then faces a choice: reproduce the inconsistency faithfully, or normalise it and risk a review comment saying it does not match the design. Both answers are bad.

If a value appears three times in a file, it is a token. Name it before the build starts, not during code review.

Defining type scale, spacing scale and colour tokens before the detailed screens are drawn costs an afternoon and removes most of the ambiguity from the entire handoff.

Write the motion down

Motion is the part most likely to be described as 'make it feel smooth' and most likely to be rebuilt three times. A usable motion spec is short: duration, easing curve, what property is animating, what triggers it, and what happens on reduced-motion.

Five lines per interaction. If the design system settles on one or two easing curves and a small set of durations, most interactions need no spec at all because they inherit the defaults.

What good looks like

A handoff we would consider complete contains the approved screens, every state for every component that has more than one, named tokens for type, spacing and colour, a short motion spec, responsive behaviour at the actual breakpoints in the codebase, and a named person who can answer a question the same day.

That last item is not a document, and it matters more than any of the others. No file anticipates everything. The difference between a handoff that lands and one that bounces is usually whether there is someone to ask.