Skip to content
Documentation

Keeping them aligned

Two catalogues describe the same interface: the Figma library on the design side and the component library on the code side. The interesting question is always whether the two still agree, and that question has an answer only if something checks it.

Two catalogues that have silently diverged are worse than one, because both sides keep citing theirs and neither knows the other has moved.

Where drift comes from

Section titled “Where drift comes from”

Four sources, in rough order of how much damage they do.

The quiet variant. A screen needed something slightly different; a developer added a prop. It is real, it is used, and it exists in no design file. Six months later a designer draws it from scratch, differently, because they did not know it was there.

This is what happens to a change request that was too slow, and it is the reason turnaround time on change requests belongs on this page rather than in a process document.

The Figma-only component. A designer draws a pattern, it ships in a mockup, nothing implements it. It accumulates usages in design files and expectations in stakeholders’ heads, and the first implementation attempt discovers it cannot be built as drawn.

The token edited downstream. A generated file gets a manual fix under deadline. The next generation reverts it, someone re-applies it, and the pipeline is now something people work around rather than through.

The unannounced deprecation. Design retires a pattern; code keeps it because nobody said. It stays in production for a year, in exactly the screens nobody looks at.

What to check, and how often

Section titled “What to check, and how often”
Check How Cadence
Tokens match the source Regenerate in CI and fail on a diff Every build
Every code component has a design counterpart Compare names against the Figma library index Weekly, automatable
Every design component has an implementation, or a status Same list, other direction Weekly
Every component state has a story Enumerate stories against the contract Every build
The rendered component matches the design A person looks at the story next to the frame Per change, in critique

The first four are mechanical and should never be a human’s job. The fifth cannot be automated and should never be attempted mechanically — a pixel diff between Figma and a browser produces false failures forever, because they are two different renderers with two different text engines.

Which side wins

Section titled “Which side wins”

State it in advance, because deciding it during a disagreement produces a negotiation instead of a rule.

  • For a value or a visual decision, the design system wins. It is the source; code is a consumer.
  • For behaviour, keyboard model, or announcement, the component library wins. Design files cannot express these, so a design that implies something different is under-specified rather than authoritative.
  • For “this exists”, neither wins automatically — it is a contract change, and it goes through the same route as any other: proposed, reviewed by both, added upstream.

The general form: whoever owns the medium the decision lives in wins, and anything else is a change request.

Making drift visible

Section titled “Making drift visible”

The cheapest useful instrument is a single reconciliation page listing, side by side, what exists in each catalogue and what is missing from the other. It is a list of names and it takes an afternoon to generate.

Its value is not the report. It is that drift becomes a number that can go up, which is the only form in which this kind of problem gets attention before it is a crisis.

The honest position

Section titled “The honest position”

Perfect alignment is not the goal and is not achievable. The goal is that divergences are known, visible, and either scheduled or accepted on purpose.

A library with eleven documented divergences and a plan is in far better shape than one that claims none and has never checked.

Where it connects

Section titled “Where it connects”