Skip to content
Algolithic
All articles

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.

June OkaforHead of Design

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.

  • Design systems
  • UI
  • Tokens

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.

↳Keep reading

More from the workbench.

Engineering2 min read

Shipping weekly without breaking things

Small pull requests, feature flags and a deliberately boring CI pipeline let us release every week — even on products with thousands of daily users.

By Theo Park

Product2 min read

How we scope an MVP in two weeks

A short, structured discovery turns a big idea into a plan you can build, budget and test — without a 60-page spec nobody reads.

By Mara Quinn