The Handoff Is the Product: What Breaks Between Figma and Production

“The build doesn’t match the design” is the most common complaint we hear on inherited projects. It is almost never because an engineer was careless. It is because the design file and the codebase were describing the same thing in two different languages, and nobody wrote the dictionary.

What actually diverges

Colour is rarely the problem — hex values copy across fine. What diverges is everything with logic in it: spacing at breakpoints the mockup didn’t cover, focus and disabled states nobody drew, what a card does when the title runs to three lines, and what the empty state looks like.

A static frame cannot express those. So an engineer decides, ships something reasonable, and the designer sees a different product.

The contract that fixes it

One shared token set as the source of truth, exported from design and consumed by code. Not a document describing the tokens — the actual values, in a file both sides build from. If a colour isn’t in it, it doesn’t exist.

Then: every component gets its states drawn before it gets built. Default, hover, focus, active, disabled, loading, error, empty. It is tedious and it removes about 80% of the drift.

The test

Ask your designer and your engineer what the disabled state of the primary button looks like. If you get two answers, you don’t have a design system — you have a folder of pictures.