What is a design system and how do you build one?

In short

A design system is a shared toolkit so your team doesn’t redraw every screen. What a button looks like in which state, and the name it is called by in the code, is written down in one place.

Therese Fessenden of the Nielsen Norman Group defines it as a complete set of standards, made of reusable components and patterns, for managing design at scale. I put it more briefly: don’t make the same decision twice.

The system isn’t a Figma file. The Figma file is the design-side copy of the system. The real system is the components that live in the code. The documentation for them and the people who maintain them are part of the system too.

• In my view it is worth it for a small team too, but not in the first week. The benefit shows as the product grows.
• The system’s smallest unit is named values called design tokens.

Design system, style guide and component library: the difference

Style guide, component library and design system are often confused. The reason: the first two sit inside the third. According to NN/g, a design system’s repository usually contains a style guide, a component library and a pattern library.

Part	What it describes	Example
Style guide	Brand rules, content guidelines such as tone of voice, visual and interaction standards.	“Headings in Bricolage Grotesque, body text in Instrument Sans.”
Component library	Individual parts of the interface. Each entry has a name, description, attributes, states including the default, and a code example.	Button: primary, secondary; normal, disabled.
Pattern library	Layouts and templates in which components solve a task together.	Address form, empty-list screen.
Design system	All of that, plus the team and the rules that govern it.	When a component is added and who approves it.

NN/g notes that the terms component library and pattern library are sometimes used interchangeably. Even so, there is a difference. A component is a single part; a pattern is the way parts come together.

NN/g stresses one more point: the system is only as good as the team that governs it. In my view, a component library without an owner turns over time into an archive nobody trusts.

So when do you need one? According to NN/g, a design system creates the most value when a company expects years of repetitive design work. For a proof of concept or an early prototype, a full system very likely won’t pay off in the short term.

Building everything from scratch isn’t the only way either. NN/g names three: adopt a ready-made system as it is, adapt it, or build your own. Adopting is the cheapest and fastest. The more you adapt, the higher the cost; building your own costs the most time and money.

Layers: token, component, pattern, page

Thinking of a design system in layers shows what depends on what. I use four layers, and each relies only on the one below it.

1. Layer 1TokenNamed values: colour, spacing, font size, corner radius.--accent
2. Layer 2ComponentA single part that reads tokens: button, badge, form field, card..btn--primary
3. Layer 3PatternComponents that solve a task together: payment form, empty state.Address form
4. Layer 4PageThe screen where patterns sit side by side with real content./checkout

Figure: each layer uses only the layer below it. When a token changes, the change travels up into every page.

1. Token

A token is a name for a value. Instead of #FF6B3D you write --accent. The format document the Design Tokens Community Group published in October 2025 defines a token as a pair of at least a name and a value.

The same document also lets one token point to another token. That is called an alias. The token “accent colour”, for example, points to the token “orange 500”. When the brand colour changes, one line changes. The kinds of tokens and the file format are covered separately in the glossary entry on design tokens.

2. Component

A component is a part that reads tokens and does a single job: button, badge, form field. A good component knows no raw colour, only tokens. That is why it looks right in a dark area too.

When designing a component, the states are the easiest thing to forget. Yet users also see the button when it is in focus or when the system is waiting for a response. Each of these states belongs to the component.

3. Pattern

A pattern is a combination of components that solves a user task. An address form made of label, field, error message and button is an example. The rules for forms are collected in the form design pattern.

4. Page

On the page, patterns come together with real content. This is also where it shows whether the system works. A long product name or an empty list exposes gaps in the system at once.

Brad Frost’s 2016 book Atomic Design proposes a similar model: atoms, molecules, organisms, templates and pages. Frost writes that these stages aren’t steps you work through in order but a mental model you think of together. My four layers are a simplified form of this model.

Building a design system: step by step

Building a system from scratch doesn’t start like a big design project. Your product already contains a hidden system; it is just messy. The first step is to make it visible.

1. Make an inventory. In 2013 Brad Frost called this an interface inventory: a collected list of the parts the product is made of. Take screenshots of each kind of component and group them on one page. According to Frost, the point isn’t to capture every instance but to collect the variants that look different.

2. Show the inconsistencies. Once the inventory is done, you see many different buttons side by side that do the same job. Frost writes that it matters to separate deliberate from accidental variation. According to him, the inventory also helps convince managers or clients of a system.

3. Settle the tokens. Count colours, font sizes, spacing and corner radii, and merge similar ones. First write the raw values (primitive tokens), then the names with meaning (semantic tokens). Check contrast at this step too. You can use the contrast checker for that.

4. Start with the most used component. Don’t build them all at once. The inventory shows you which part repeats most often. Write down variants and states for each, then code it.

5. Write the documentation next to the component. According to NN/g, an entry in the component library has a name, description, attributes, states and a code example. I add one line: when not to use it.

6. Settle governance from the start. Who adds a new component, who approves it, and how is an old one removed? NN/g writes that the system needs constant maintenance and oversight. Otherwise it goes out of date and fragments.

On team size NN/g has a recommendation: at least one interaction designer, one visual designer and one developer. If these roles exist in the company, the ideal team adds a part-time researcher, an architecture role and a content role. NN/g also recommends an executive sponsor who provides money and resources.

In a small startup, all these roles sit with one or two people. That isn’t a problem. What matters is that everyone knows who owns the system.

Don’t push accessibility to the end when building. Once a component is built right, it works everywhere it is used. For me, testing WCAG criteria at component level is cheaper than fixing page by page.

Does the system work?

The easiest way to see whether your system holds up is to watch how a new screen is made. If design puts new screens together mostly from ready-made parts, the system works.

The opposite sign is just as easy to see. If development copies a component and changes it instead of using it, the component doesn’t cover a need. Don’t read that as a mistake but as a request to the system.

Once a month I search the code for raw colours and raw sizes. Every hit shows either a missing token or a screen that has fallen out of the system.

From Figma to code

A design system is only a system once it also lives in the code with the same names. If a button is called “Primary/Large” in Figma and BigBlueButton in the code, the team translates every day.

Figma builds this bridge with variables. The Figma help defines variables as reusable values that can be applied to different design properties. The same document writes that variables and modes can be used to implement design tokens.

Modes solve theming. You give a variable its own value per mode, for example for light and dark themes. In code, that corresponds to the same token name getting a different value in another theme.

My workflow looks like this:

1. In Figma I write token names exactly as in the code. color/accent becomes --accent in the code.
2. I match the component’s variant names with the modifier names in the code: “Primary” in Figma, btn--primary in the code.
3. Development can also access variables in Dev Mode when inspecting an element. Figma describes this in a help article of its own.
4. I make the code the single source of truth. Figma follows the code, not the other way round.

The last point isn’t everyone’s choice. Some teams take Figma as the reference. But what reaches users is the code. When Figma and code drift apart, users always see the code, so I take the code as the reference.

Figma also allows reading and writing variables through the REST API. The documentation has an example of a GitHub Action that syncs variables with the codebase. Small teams often don’t need this. If there are only a handful of tokens, syncing by hand is enough.

Try it: mini component set

The set below has three components: button, badge and card. All read the same token set. Choose a component, a variant and a state to see how an entry in the component library reads.

Try it: mini component set

Checkout

Code: class="btn btn--primary"

Button, primary, normal. For the screen’s main action. There is one primary button per screen, so users don’t have to look for what to press.

In the normal state, the button is ready. The label says what happens when you press it.

A small set of this website’s components. Choose a component, variant and state: the preview, code line and usage note change together. Because a badge isn’t clicked, its states are locked.

All the usage notes from the demo are in the table below. Every entry in the component library should say at least this much.

Component	Variant	When to use it
Button	Primary	The screen’s main action. There is one per screen.
Button	Secondary	The second option next to the main action. Looks calmer.
Button	Warning	An action that is hard to undo. The label says clearly what happens.
Badge	Primary	A completed or positive state, such as “Shipped”.
Badge	Secondary	A neutral label, such as “Draft”.
Badge	Warning	A state that expects a step from the user, such as “Payment due”.
Card	Primary	A single highlighted topic. The fill colour makes sure it is read first.
Card	Secondary	An ordinary entry in a list.
Card	Warning	Content that expects a step from the user.

States matter as much as variants. The focus ring, for example, shows keyboard users where they are on the page. The loading state prevents a second click so the same request isn’t sent twice.

The W3C’s ARIA Authoring Practices Guide (APG) recommends the aria-pressed attribute for toggle buttons with the two states pressed and not pressed. According to the guide, the label of such a button shouldn’t change when the state changes. The selection buttons in the demo follow this.

Common mistakes

Mistaking the system for a library. Publishing a Figma file or an npm package doesn’t mean building a system. If it isn’t clear who maintains it, the library goes out of date over time.

Drawing without making an inventory. New components made without looking at the existing product just add one more button to the old ones. Count what is there first.

Designing only the normal state. If focus, disabled, error and loading aren’t drawn, development invents them itself. A different loading indicator appears on every screen.

Writing raw values into the component. If the button contains #FF6B3D, a dark theme or a brand change needs a separate fix in every component. The component should only read the semantic token.

Naming tokens after colours. A token called --orange lies as soon as the brand turns purple. Semantic tokens describe the function: --accent, --text-muted.

Turning every wish into a component. Something that appears only once on a single screen isn’t a component. I only add a part to the system once it is used in at least two places.

Burying the documentation on a separate website. A documentation site nobody opens is as good as none. The rule should sit right next to the component’s code.

Making colour the only signal. A red badge alone doesn’t say “There is a problem”. People who have trouble telling colours apart read the text, and the screen reader reads the text too. Always name the state in words as well.

My note

The page you are reading is built with a design system too. The ux.center system has four layers, and each relies only on the one below: tokens, components, sections and page.

The tokens sit in a single file in two levels. The first level holds raw values, such as cream, ink and orange tones. The second holds the semantic names the components read: --bg, --text, --accent. A dark or coloured area (mood) changes only this second level.

For components there is a simple rule: each component has one CSS file and one Python function. Today there are 24 component files; the button, badge and card from the demo are among them. None knows a raw colour, which is why they work in a dark area too.

The sections build on that. Each home page section brings its own markup module, style file and, if needed, a motion script. The build script combines everything in order into one CSS and one JS file.

The most valuable thing for me is a test tool. Before and after every change that shouldn’t alter the look, I record the style and box of every element on desktop and mobile. Only when both recordings are exactly the same does the work count as done. Keeping a system takes more effort than building it.

If you want to build a system like this for your product or bring an existing one into code, the Design & Ship Sprint is made for exactly that. I deliver design and code into your repository.