Design2 min read
Design systems that survive contact with engineering
A component library only works if designers and developers share the same names, tokens and decisions. Here is how we keep them in sync.
Plenty of design systems look beautiful in a design file and then quietly drift away from the product. Six months later the buttons in production have four slightly different radii and nobody knows which one is "right".
The fix isn't more documentation. It's treating the system as a shared product between design and engineering from day one.
Start from the product, not the library
We don't begin by designing forty components in isolation. We design two or three real screens first, then extract the patterns that repeat. Components earn their place by being used — which keeps the system small and honest.
Use the same names everywhere
If designers call it "surface-raised" and the code calls it bg-gray-100, the system has already split in two. We define design tokens once and use the same names in the design tool and in code:
:root {
--color-surface: #f5f4eb;
--color-surface-raised: #ffffff;
--color-accent: #ea3779;
--radius-control: 4px;
--space-3: 0.75rem;
}
When a token changes, it changes everywhere, and nobody has to hunt through screens to find the old value.
Document decisions, not just components
A component page that shows variants is useful. A component page that explains when not to use it is far more useful. For each component we record:
- What problem it solves
- When to reach for something else instead
- Accessibility requirements, such as focus order and contrast
- Content guidelines: label length, tone, error messages
Make contributing easy
The fastest way to kill a design system is to make it a gate. Teams should be able to propose a new component or variant with a lightweight template, get a review within days, and ship it. A system that can't keep up with the product will simply be worked around.
Check it in the browser
Finally, we review components in the browser, not just in mockups. Real text, real data and real screen readers expose problems a static frame never will — and they're the version your users actually see.
About the author
June Okafor · Head of Design
June leads design from the first user interview to the design systems engineers build on, with accessibility treated as a requirement, not a polish step.