Building a Component Library in Figma That Matches Production Code

We used to build Figma components the way that felt natural in Figma, optimizing for how designers wanted to compose screens, with variant properties like 'size' and 'style' that didn't map to anything in the actual React component props. Handoff on a client's internal tools platform meant engineers had to reverse-engineer what each Figma variant was supposed to correspond to in code, and the mapping was inconsistent enough that two engineers building the same component from the same Figma frame sometimes produced slightly different prop names.

The fix was treating the Figma component's variant properties as a direct mirror of the code component's actual API, not a separate, designer-friendly abstraction. If the Button component in code accepts a variant prop of primary, secondary, or ghost, the Figma component's variant property is named variant with exactly those three options, not 'style' with 'filled' and 'outline.' It's a small naming discipline that removes an entire category of handoff ambiguity.

This constrained how designers could compose things in Figma, which was initially unpopular internally, since it meant giving up some Figma-native flexibility, like nesting variant overrides in ways the real component couldn't actually support. We decided that constraint was the point: if a composition isn't achievable in code, it shouldn't be easy to build in Figma either, because otherwise designers ship mockups that quietly promise something engineering has to walk back later.

We paired this with Code Connect-style mapping once that tooling matured, linking each Figma component directly to its source file in the codebase, so an engineer picking up a design could jump straight to the real implementation and see exactly which props were being used in a given design, rather than inferring it from a static frame. This cut a meaningful amount of back-and-forth Slack clarification during implementation on later projects.

The library still isn't perfectly synced, and it never will be automatically; new component variants get added in code between design system audits, and Figma occasionally drifts ahead when a designer needs something new before engineering has built it. What changed is that drift is now the exception we actively look for and reconcile on a schedule, rather than a silent, accumulating gap nobody owned.