Skip to main content
All Notes

Design systems are a code problem

A Figma library is documentation. A component library is a design system. They are not the same thing.

A Figma library is not a design system. It's a design system proposal.

The real system is whatever lives in the codebase. If a component only exists in Figma, it doesn't exist — a developer will rebuild it from scratch, make slightly different decisions, and your system will fork from reality the day it ships.

I've seen this happen. You spend three months building a beautiful library. Tokens, variants, auto layout, detailed documentation. Then engineering looks at it, nods, and builds their own component library in React. Two months later you're in a design review asking why the button doesn't match — and the honest answer is: it never did, because the source of truth was always the code.


When I built Vision UI at MontyCloud, I built it in two places simultaneously: Figma and Storybook. Radix UI for accessible primitives, Tailwind for the token layer, React for the component API. The Figma file and the component library had to agree — not approximately, exactly.

This changed what I paid attention to. In Figma alone, you can name a token color/primary/500 and feel good about it. In code, you have to think about what that becomes as a CSS custom property, how it cascades in dark mode, what happens when a component overrides it. The discipline of shipping it in code forces clarity that Figma doesn't.

Figma variables are useful. But CSS custom properties are the actual tokens. The ones in Figma describe intent. The ones in CSS create consistency at scale. If those two sets of tokens diverge, you're maintaining two systems, and the one in your stylesheet always wins.


The drift problem is structural. Figma components get updated when designers update them. Code components get updated when engineers update them. These are different people, different schedules, different priorities. The only way to keep them in sync is to have someone who can work in both — or to accept that the two will drift and treat the code as the single source of truth.

This is the design engineer's real advantage. Not that they're faster, or more technical, or better at Figma. It's that they can close the loop. Build the Figma component and write the React component in the same session. Name the token once and use it in both places. Ship it and own it.


There's an uncomfortable version of this: if you can't write the component yourself, you don't fully own the system.

You can design it. You can specify it in detail. But you're always dependent on someone else to make it real, which means you're always one miscommunication away from something that almost matches. That gap is where design systems fail — not in the architecture, not in the token naming, not in the documentation. In the handoff.

The fix isn't to make designers into engineers. It's to recognize that a design system is fundamentally a software artifact. Design it like one.


The Figma file is where decisions get made. The codebase is where they live.

Both matter. But if you have to choose which one is real, choose the one that ships.


You might like these too!