What is a design system, really?

A project with nothing to lean on

At first, the differences were small. Over time, though, each screen carried its own decisions about buttons, spacing, and colour. Without a shared source of truth, the interface slowly drifted, and fixing a button in one place did not always fix it everywhere else.

Seeing that pattern took me back to earlier projects, where I had worked alongside UI/UX designers and other frontend developers. There, a bug in a button could often be fixed once and shared across every screen that used it. Testing tended to be simpler because the same piece behaved in familiar ways, and even conversations felt clearer: designers, developers, and QA could point to the same thing when they said “the primary button”.

That contrast gave me a starting point. Rather than adding more rules, I began building a design system to give the team a shared foundation.

A shared foundation, built step by step

A design system can begin as a small shared reference point rather than a large library. For us, it meant writing down the decisions that kept appearing in the interface, then making them easier to reuse in both design and code.

Start with tokens

Tokens are the raw values underneath the UI: colours, spacing, typography, corner radius, shadows, and sometimes layout rules such as breakpoints. Instead of choosing these values again on every screen, the team agrees on a small set once and gives each value a purpose.

For example, a token might describe a role, such as brand-primary, text-muted, or space-16, rather than a particular hex value or a one-off margin. That makes the decision easier to use in Figma and in code, and easier to change later without hunting through every screen.

On the search platform, this was the first step. Agreeing on colours, spacing, font sizes, and corner radius once removed a whole category of “is this the right shade?” questions.

Reuse components, then build the gaps

The next question was which components we actually needed. For common patterns such as buttons, inputs, tables, or dialogs, an existing library like MUI or Ant Design can be a useful starting point. The team can theme those components with its tokens instead of rebuilding familiar behaviour from scratch.

Custom components still have a place. They are worth building when a repeated pattern belongs specifically to the product, such as a search-result card with its own content, states, and actions. The key is to build it once, give it a clear API and usage guidance, then reuse it rather than recreating it on each screen.

Keep the decisions visible

Components need a little context around them. A short note can explain what a component is for, when to use it, how it behaves, and what it looks like in the product. Figma, Storybook, and token files can then become the places where the same decisions stay visible.

We added guidance gradually. One simple guideline that worked especially well for us was aiming for one primary action per screen. It gave each screen a clearer focus without turning the system into a long list of rules.

What I’ve taken away so far

Putting this together changed how I think about a design system. It does not need to begin as a polished library with every component already made. It can begin with the decisions a team keeps making, then give those decisions a place to live.

For this project, the useful part was simple: fewer one-off choices, clearer conversations, and a more consistent experience as the product grows. Tokens, components, and guidance each help in a different way, but they all give the team something shared to build from.

That is the part that felt clearer once we started. Working out how to keep the system useful as the product grows is a story for the next post.