The Spacing Was Right in Figma and Wrong in Production

The design handoff is a contract the codebase keeps breaking. The spacing was right in Figma. The padding on the shipped card is two pixels off, the hover state nobody drew is beige, and the empty state nobody specified says "undefined." The file was correct, and the product shipped wrong.

Multiply that across a quarter of releases and the design system stops being a system. It becomes a suggestion the frontend considered.

This keeps happening because neither side is lazy. The handoff, as most teams run it, has no mechanism to enforce itself. A screenshot is not a contract. A redline is not a build step. If the only thing standing between a token and production is a developer squinting at a comment, drift is the default outcome.

The File and the Codebase Keep Disagreeing

Walk through a typical sprint and the failure points are boring and predictable. A designer updates a spacing scale in one frame but not the eleven others that inherit from it. An engineer picks the nearest Tailwind value because the exact one isn't in the config. A product manager approves a flow that never specified what happens when the list is empty, when the API is slow, when the user's name is 40 characters long.

None of these are dramatic failures. They're small, compounding decisions made in isolation, and they add up to a product that no longer matches its own documentation.

Porto Theme walks through this at length in a piece arguing that the design handoff is the contract the codebase keeps breaking: two sources of truth, one shipped product, and no referee. The file wins the review. The codebase wins at runtime. The user sees whichever one got the last word, and that word is almost always wrong in a way neither team meant.

Why Better Redlines and Longer Specs Don't Fix It

The obvious response is to document harder. Add annotations. Write an acceptance checklist. Stand up a weekly design QA.

Teams try this and it holds for about one release cycle before the overhead collapses it. Nobody reads a 40-page spec. Nobody runs through 120 states by hand. The reviewer who caught the padding issue last month is on vacation this month, and the drift returns.

The deeper problem is that redlines describe the destination without constraining the path. A spec that says "use spacing-md" relies on a human to translate "spacing-md" into 12px by hand, in every component, across every platform. One of those humans will reach for 16px because it looked tighter on their monitor.

Call it a tooling problem, not a discipline one. If the value lives in a design file as a label and in the code as a magic number, nothing connects the two except good intentions.

Dev Mode and inspector panels help, but they still ask the developer to do the translation by hand. The handoff needs to stop being a conversation and start being a build artifact.

Tokens and Shared Components Make the Contract Enforceable

Design tokens close the loop by making the design decision itself the source both tools consume. Atlassian's design system defines tokens as a single store of named design decisions, which is the plain version of what makes this work: the file reads from the same place the code does. Change the value once and both move together.

None of this removes designers or developers from the loop. It moves their disagreements earlier, into pull requests and token diffs, where they can be resolved in minutes instead of discovered in production by a user whose name broke the header.

What to Build First

Start with the three or four token categories that cause the most drift: spacing, color, typography, and radius. Get them into a shared JSON source, generate the platform outputs from that source, and point both the design file and the codebase at the result. Then pick the five components that show up on every screen and move them into a shared library with their states as fixtures. Then wire visual regression into CI so the next unintended change gets caught by a machine instead of a user.

The handoff stops being a document the two sides argue about. It becomes a build the two sides maintain together. The file and the codebase can still disagree; they just can't ship while they do.