A design handoff a developer will not quietly ignore

A handoff fails quietly. The developer does not complain — they make a reasonable guess, ship it, and the designer finds out three weeks later that the empty state says "No data" in a font nobody chose.

Nearly always, the guess was forced. The file contained one perfect screen and no answer to the five questions that come up the moment someone starts building.

1 · Spacing, as a system rather than as pixels

A developer measuring gaps off a mockup will find 16, 17 and 15 where you meant 16 three times. They will either reproduce the inconsistency faithfully or invent their own scale.

Give them the scale instead: 4, 8, 12, 16, 24, 32, 48, 64. Use only those values, and say so in the file. Then "the gap between the card and the heading" has one correct answer rather than a measurement.

Same for type. A named ramp — display, h1, h2, body, small, caption — with size, weight and line height. Six entries beat forty-three arbitrary sizes, and the file is easier to maintain too.

2 · Every state, not just the happy one

This is the big one. For each interactive element, the build needs:

• Default — the one you always draw.
• Hover — and what it looks like on touch, where hover does not exist.
• Focus — keyboard users need a visible ring. If you do not design it, the browser's default appears, and it will not match anything.
• Active / pressed.
• Disabled — and why it is disabled, because that usually needs a tooltip you have not drawn either.
• Loading — does the button keep its width? If not, the layout jumps.
• Error — on the field, not only in a banner at the top.

Seven states per component sounds heavy until you count how many bugs come from the missing six.

3 · Empty, one, and far too many

Designers draw the screen with four cards because four cards look good. Production has zero, one, or nine hundred.

Draw all three. The empty state is a real screen with a heading, a sentence explaining what will appear, and the action that creates the first item — it is the most-seen screen for a new user and the least-designed one in our industry. The overflow state tells the developer whether to paginate, scroll or truncate, which is an architectural decision they will otherwise make alone.

And draw the long name. "Muhammad Abdul Rahman Khan" instead of "Ali". Half of all layout bugs are a name, a title or a city that was longer than the mockup.

4 · Write the words, all of them

Every error message, every confirmation, every tooltip, every empty state. If the design says [error message], the developer will write it, and it will say "An error occurred."

Real copy is also a design constraint. "Save" and "Save and continue to billing" are not the same button, and you find that out while designing rather than after.

The file structure we hand over

Four pages, in this order:

1. Foundations — colour tokens with names and hex values, the type ramp, the spacing scale, radii, shadows, icon set.
2. Components — every component with every state, laid out in a grid, annotated with the token names rather than raw values. "Padding: space-16" not "16px", so a later change to the scale propagates.
3. Screens — the real flows at the real breakpoints we support. Not every width, just the ones that exist: mobile, tablet, desktop.
4. Edge cases — empty, loading, error, overflow, long content, offline.

Then a fifteen-minute call walking through it. Not a presentation — a Q&A. The developer asks the five questions, and either the file answers them or we have just found what is missing, while it still costs ten minutes instead of a sprint.

How you know it worked

You review the built screens and have nothing to say about spacing. Every comment is about behaviour and copy — the things that genuinely could not be decided in a static file.

If your review notes are full of "4px too far", the handoff was the problem, not the developer.