The gap between Figma and code: how it starts

A setup that looked complete

A couple of years ago, a platform redesign wrapped up looking like it had gone the right way.

First, the exploration phase: visual language locked in, light and dark mode worked through, screens redesigned. Then, the execution: the rest of the product redesigned and annotated inline, connector lines linking triggers to destination screens and overlays to clearly map navigation paths. Prototype flows for the interactions that needed motion. A Figma library with design tokens and a full set of reusable components, organised, documented, and ready to hand over. 

That felt like a natural end. It wasn't.

Good enough until it isn't

The library was handed to the client's design team.

From there, it moved to their engineering team. That transition happened without us. Their design and engineering teams were in different offices, different time zones, with infrequent sync. No Storybook. No shared component inventory. No named owner for the gap between design and code.

The tokens made it across. CSS variables were extracted from Figma and implemented correctly. That part worked. Everything beyond that came down to how closely developers chose to follow the specs, and without a feedback loop, close enough became good enough.

Seven or eight months later, when the redesigned UI started to be piloted with customers, discrepancies began to surface. Button variants had drifted. Icons slightly off. Stroke widths didn't match. Spacing was close, but not right. None of it would fail a functional test, but together it produced a product that felt quietly unfinished in a way users couldn't quite name. When complaint data came in, more than half of it had nothing to do with broken features. Things looked wrong, or felt wrong. Often both.

One example made the point clear. A page header the engineering team had made sticky, even though it was never designed to be, reduced the visible area for the content that mattered most on that page. Nothing was broken. But the experience was noticeably worse, and it came directly from an assumption neither side had thought to question out loud. That's the category of problem that never shows up in a functional test.

No library, however well built, can close the gap on its own once it leaves the hands of the team that created it.

The long way in

We heard about it. We pushed to be more involved on the code side. The idea landed well. The permission didn't.

It wasn't a budget issue, but a political one. Their development team had built the product from the ground up, and bringing in an outside studio felt like a challenge to their judgment, not a support to it. Nobody in management was willing to make that call.

Part of that was on us. The offer hadn't made the value clear enough.

What we were proposing wasn't a code review or a handover audit. It was taking the infrastructure work off their plate: primitive components, design tokens, Storybook documentation, accessibility semantics, versioning, breaking changes. The work that slows a product team down without ever feeling like progress. That pitch never landed the way it should have. So, we waited.

The client's own design team got there first. They were the ones living with the mismatch every day and the most tired of it. At some point we stopped waiting and scheduled a meeting directly with upper management. Visual comparisons, complaint patterns, and the design team's frustration laid out clearly. That was the moment things shifted.

The full picture

Once we had access, the picture was more complicated than expected.

The Figma library wasn't as intact as it had been at handover. Hundreds of screens were added by the internal team after they took ownership. Designers had been filling gaps on their own, building components locally when the original set didn't cover their needs. No documentation standards, no consistency checks, no connection to the existing components. It made sense in the moment, but it added up over time. The drift wasn't only happening in code.

If the Figma files had drifted, the code had drifted further. And unlike the design files, the code is what ends up in front of customers. The instinct was to tighten the handover: more redlines, stricter specs, clearer documentation. But that assumes Figma is the stable reference and code needs to catch up to it. But Figma wasn't fully stable. Anchoring the fix to something that was itself moving wasn't a fix at all.

Code as the source of truth

The decision: make code the source of truth.

Not because code is inherently better than Figma, and not as an argument for starting in code. If you're building a new product and the visual language is still being worked out, Figma is still the right place to explore. This wasn't that situation. The design was mature, the screens were signed off, and the failure was in the execution, not exploration.

Code is what gets built and what users interact with. When both Figma and code have drifted, and one has to anchor the other, it should be the one closest to the customer. Figma can inform and guide, but it can't define a reality it no longer reflects.

That doesn't mean design steps back. It means Figma stops pretending to define reality when reality lies elsewhere.

The underlying principle

The failure this project was recovering from is more common than most teams acknowledge. A well-built library. A competent handover. Good intentions throughout. The gap persisted because nothing connected the design to the implemented product, and nobody was explicitly responsible for monitoring it.

That's the part most teams skip. Not the library, not the handover, but the ongoing ownership of the space in between. Figma is a critical communication tool. In a mature product, it should describe reality, not define it.

That's how the gap starts. How we closed it will be covered next.