Design Systems That Survive the Handoff to Engineering

Figma components and code components drift apart within weeks without a shared source of truth — a structural problem our design systems work is built to solve. The drift happens in a specific, predictable pattern. Design produces a component library that looks correct in Figma. Engineering implements the components in code. The first iteration is close. The second iteration has small discrepancies — a spacing value that was rounded, a colour that used the closest available Tailwind token rather than the exact design value, a font weight that was approximated. By the sixth sprint, the Figma file and the codebase describe slightly different products.

This isn't a failure of craftsmanship on either side. It's a structural problem: two representations of the same thing, maintained independently, will naturally drift unless there's an active mechanism keeping them synchronised. Most teams don't have that mechanism — they have a design review step that catches obvious regressions but misses the accumulation of small ones.

The solution isn't more rigorous design review. It's a single source of truth for the values that can't drift: colour, spacing, typography, radius, shadow. When those values live in design tokens that feed both the Figma variables and the code theme, a change to the token propagates to both. The drift problem doesn't disappear entirely — component logic and layout still need review — but the most common sources of drift are eliminated.

Starting with a token layer that both design and code reference directly. A design token is a named value: `--color-accent: #5b7fff`, `--spacing-4: 1rem`, `--radius-md: 0.75rem`. The name is the contract. The value can change without breaking anything that references the name. When the brand colour shifts from blue to teal, you change one value and every component that references `--color-accent` updates automatically — in both Figma (via Figma Variables) and in code (via CSS custom properties or a JS theme object).

Building tokens before components forces two useful decisions. First, it forces the design team to name things deliberately. You can't have 47 slightly different shades of grey with no naming convention. You need a system: neutral-50, neutral-100, through neutral-950, with semantic aliases (surface, border, text-secondary) that map to the neutral scale. Second, it forces agreement between design and engineering on the naming convention before either side has built anything that depends on it — which is the only time when changing the convention is cheap.

The token set doesn't need to be large. For most projects, a complete token set covers: colour (brand, neutral, semantic, feedback), typography (size, weight, line-height, letter-spacing), spacing (a 4px or 8px base scale), border radius (3–4 values), shadow (2–3 levels), and transition timing (2–3 durations). Anything beyond this is usually premature — add tokens when you find yourself hardcoding the same value in three different places.

Keeping usage guidelines next to the components, not in a separate wiki nobody opens. Documentation that lives in a separate Notion page or Confluence wiki has a half-life of about six weeks. After that, the wiki and the codebase diverge, and nobody knows which one is canonical. The engineers stop consulting the wiki. New designers can't trust the wiki. The design system becomes tribal knowledge again.

The solution is to make documentation inseparable from the component. In Storybook, this means writing the usage notes, the do/don't examples, and the prop documentation inside the story file. If you're not using Storybook, it means keeping a usage comment block inside the component file that explains the intent, the expected variants, and the accessibility requirements. It's not as pretty as a dedicated documentation site, but it's there when someone is looking at the component file, which is when they actually need it.

Figma supports this through component descriptions, property descriptions, and documentation links inside the component itself. A Figma component that has no description is an invitation for misuse. One that describes what it's for, what variants exist, and when to use each variant gives the next designer opening that file the context they need without having to find someone to ask.

A dedicated design-QA pass after build, before launch. Most project timelines include design review at the prototype stage and then assume engineering will implement correctly. They skip the step of having a designer review the actual built product against the design file before launch.

This is the step that catches the accumulated drift — the spacing that's 14px instead of 16px, the button border radius that's 6px instead of 8px, the mobile nav that works correctly but looks slightly different from the design because the engineer eyeballed it. Individually, none of these regressions are catastrophic. Together, they produce a product that looks subtly wrong in a way that's hard to pinpoint but easy to feel.

Building a design QA pass into the project timeline — typically 2–3 days in the week before launch — changes the outcome. The designer reviews at full fidelity on each target device, creates a single consolidated list of corrections, and the engineer addresses them in one focused session. The result is a shipped product that matches the design file, not a product that was close enough at handoff.