Design systems that live in code

By Imran Sheikh · 2026-11-12 · Product design · 4 min read

Key points

  • The code is the source of truth, and the design file explains it.
  • Tokens and a few components cover most of a product.
  • A live styleguide page keeps designers and developers aligned.

A design system in a design file is a proposal. A design system in the codebase is a fact. The first can drift from the product within a month. The second is the product.

I have spent fifteen years in product design, eight of them leading teams. I led Chartboost’s design system at Zynga, and I now design in the repo every day. The lesson I keep coming back to is that a system works best when it lives where the product is built.

Why a file alone drifts

In the usual setup, designers maintain components in a design tool and developers rebuild them in code. Two versions of the same button now exist. Each change needs to be made twice, and the second copy is always late. Over time the gap grows, and people stop trusting the file.

The cost shows up in small ways. A developer eyeballs a spacing value because the file is out of date. A designer approves a screen that does not match the library. Reviews turn into pixel arguments instead of conversations about the experience.

None of this comes from carelessness. It comes from keeping the truth in two places. Remove one of them and the problem shrinks.

Developers and designers also read the same system differently. A designer thinks in screens and flows. A developer thinks in components and states. A shared codebase gives both a common language, because a component name in the file is the same name used in the review.

Start with tokens

Tokens are the cheapest and most valuable part of a system. They are named values for color, type, space, radius and motion. Put them in the repo as variables, and let components reference them. A global change then becomes a one-line edit.

Name tokens by role. Use surface and ink-muted instead of gray-200 and gray-600. Role names survive a rebrand and make dark mode a table swap instead of a rewrite.

  • Color: canvas, surface, line, ink, ink-muted, brand.
  • Type: a short scale named by role, plus weights.
  • Space: a base unit and a small ladder of multiples.
  • Shape: radius and border values.
  • Motion: a few durations and easing curves.

Make the one-off value hard to write. If your tooling flags a hard-coded color or an off-scale size, the system defends itself without anyone policing it.

Version the tokens the way you version code. Changes go through review, carry a short note about why, and can be rolled back. A color change that touches every screen should never arrive as a silent edit.

Build fewer components, and build them well

Teams often build too many components too early. A good system has a small core: buttons, inputs, cards, sheets, lists and a few layout primitives. Get those right, with every state covered, before you add anything specific.

A component is finished when its states are finished. Default, pressed, focused, disabled, loading and error. Add accessibility behavior at the same time, such as keyboard focus and screen reader labels. Doing this once in the shared component saves every screen from redoing it.

Resist components that exist for one screen. If a pattern appears twice, note it. If it appears three times, promote it. This rule keeps the library honest about what the product really uses.

Write a short usage note beside each component. Say when to use it and when to reach for something else. Two or three sentences prevent most misuse. Put the note in the code comments or the styleguide page so it travels with the component.

Give the system a visible home

A system needs a place people can look at it. A styleguide page that renders the tokens and components straight from the repo does the job. It is always current because it uses the same code as the product. Designers browse it. Developers copy from it. Reviewers link to it.

Tools such as Storybook can serve this role for components, and a simple route in the app can serve it for tokens. The format matters less than the rule that the page is generated from the real code.

Treat the styleguide as part of the definition of done. A new component is finished when it appears there with all its states. It becomes a habit within a few weeks, and the library stays complete without a cleanup project.

If the styleguide is hand-drawn, it will be wrong by Friday.

What the design file is still for

Design files still have a role. They are good for exploration, for sketching a flow before committing, and for explaining intent. Use them to think. Use the repo to decide.

When a design is approved, the real artifact is a pull request that uses the system. A designer who can read and edit the code can make that change directly. That is how the studio works with every client. We design in their codebase, so what we design is what ships.

How to start on an existing product

You do not need a rewrite. Audit what exists. Collect every color, font size and spacing value in use and group them. You will find a few real values and many near-duplicates. Pick the real ones, name them and replace the rest gradually.

Then migrate by screen as you touch it. Each time someone edits a screen, move it onto tokens and shared components. Within a few months the main paths use the system, and the rest follow. Progress is visible and the product keeps shipping the whole time.

Journal · Book a call · Home