Why does the shipped site stop matching the Figma file?
The gap isn’t one failure: it’s four, and they compound. A design file is a finite set of static screens; a website is an unbounded set of live states across an unbounded set of viewport widths. Somewhere between the file and the build, someone has to fill in everything the file didn’t literally show, and most projects never make that translation an explicit, checked step. It happens by improvisation instead, and improvisation is where fidelity leaks out.
- States nobody specified. A designer ships the default view of a screen: the empty cart looks fine, the form looks fine, the button looks fine. Hover, focus, loading, error and empty states are the ones that quietly don’t get drawn, so the developer building them is making design decisions under a deadline, not implementing a spec.
- Breakpoints between the ones drawn. A file usually shows mobile and desktop. Everything between those two widths (the 900px tablet, the folded-phone width, the ultrawide monitor) gets whatever judgment the developer supplies in the moment, and that judgment rarely matches what the designer would have drawn.
- Interactions described somewhere other than the file. A transition, an animation timing, a drag behaviour: described in a comment thread, a call, or a sticky note the developer never saw. If it isn’t in the file or the build brief, it doesn’t ship, however clearly someone once explained it out loud.
- No shared token system. Without a single source of truth for colour, spacing and type, every developer eyeballs a swatch and picks the nearest hex value by hand. Each individual choice looks close enough. Across a hundred components, “close enough” accumulates into a site that reads as visibly off without any single element being wrong.
Why does no one catch the drift before launch?
Most QA checks whether the site works, not whether it matches. A typical pre-launch pass tests that the form submits, the checkout completes, the links go where they should, and sometimes that Core Web Vitals pass: functional correctness, which is necessary and genuinely gets tested. Visual fidelity against the source file is a different check, and it’s the one that routinely gets skipped, because nobody on the team owns it as a formal deliverable.
The result is that drift is discovered late, if it’s discovered at all, usually by the client, after launch, comparing the live site to a file they approved weeks earlier. By then, fixing it means reopening components that were already marked done, which is the most expensive time in the project to be doing design review.
Why don’t two separate vendors catch the gap themselves?
Neither one is paid to police the seam between them. A design agency is paid to deliver a file; once it’s approved, its job is finished, regardless of how faithfully anyone else builds from it. A development agency is paid to ship working software against a brief; defending a designer’s unstated judgment call on a state nobody documented isn’t in that brief, and isn’t billable time either agency volunteers.
That leaves the client as the only party with an incentive to close the gap, and usually the party least equipped to spot it inside a codebase. It is the same seam that makes choosing between a referral and a white-label partner a question of who owns the outcome. Two vendors can each do competent, defensible work and still produce a site that doesn’t match the file, because “match the file” was never anyone’s job description. It’s a genuine structural gap, not a failure of effort on either side.
What actually closes the design-to-code gap?
Three things, in practice, and they reinforce each other rather than working alone.
- A shared token source of truth. Colour, spacing and type values defined once and consumed as variables by both the design file and the front-end codebase, so a developer is never choosing the nearest-looking value by hand. The translation from file to code becomes mechanical for the parts that can be mechanical, which removes most of the “close enough” drift before it starts.
- The same team owning design and build. Not because separate vendors are incapable, but because ownership of the outcome has to sit somewhere, and it sits most reliably with whoever can’t blame the other side. When the people who drew a state are reachable by the people building it, undocumented interactions get resolved by a hallway question instead of a guess.
- An explicit visual QA pass before launch. A formal step (not an afterthought) where every state the file defines is rendered and checked against the artboard, at every breakpoint the design covers. This is the step that’s usually missing, and it’s the cheapest of the three to add regardless of who designed and who built.
Our own design-to-code work is built around exactly this. Design tokens become code variables before a page is built, the same delivery team designs and builds so nothing gets reinterpreted crossing a wall between agencies, and every state is rendered on one page for review before anything ships, at the breakpoints the design defines. It’s the same principle behind a multi-location healthcare backlog we cleared for an agency partner: nothing re-interpreted between design and build, because it never left one team’s hands.
What should you ask a vendor before hiring them for design-to-code?
Five questions, asked before you sign, do most of the diagnostic work.
- Do design and build sit under one roof?. If not, ask directly who owns the outcome when the shipped site doesn’t match the file: not who’s at fault, who fixes it, and on whose time.
- Is there an actual token system?. Ask them to show how a colour or spacing value moves from the design file into the codebase. “We eyeball it against the swatch” is a real, useful answer: it tells you drift is coming.
- Are states documented before they’re built?. Ask how a hover, error or empty state gets specified. If the honest answer is “the developer decides while building it,” that’s improvisation with a deadline attached, not a spec.
- Is there a formal visual QA step?. Ask what happens between code-complete and launch. A vendor with a real process can describe a specific pass that checks every shipped screen against the artboard; a vendor without one describes testing that the site “works.”
- What happens when something doesn’t match?. Ask who owns the fix and how it’s handled. A vendor with a real process has a documented answer already. A vendor without one improvises the answer live, in front of you, once you’re already annoyed about the gap.
