Decision guide
If you are searching for when a design system pays off, or for a component library you can trust, you are usually here: two pages do not look like each other, a designer has drawn the third button, and someone suggests 'we need a design system' as if it were a plugin. Someone buys Storybook. Someone copies shadcn and calls it yours. Someone makes a Figma library the code never reads.
The marketing-site posts are about stack and SEO. This one is about the contract the UI has to keep when more than one person touches it. A design system is not a gallery. It is tokens you can point at, an owner who may say no, and a rule that a new button kills an old one. Without those three things you have a folder. You do not have a system you can defend.
TL;DR
The main points
- A design system is a contract: tokens, one owner, and not inventing the same button again.
- A component library without tokens is a gallery. Storybook without decisions is a slideshow.
- You need a system when you have more than one surface, or more than one person shipping UI.
- On an MVP still finding the product, three honest components beat a library you never clean up.
- Figma tokens the code does not read are decoration. The system lives where the browser renders.
- shadcn, Polaris and 'we copied Vercel' are a starter kit. They become yours only when you have said no to half of them.
Why this matters at all
A design system you have not decided costs weeks you do not see on a sprint board. Every new page reopens colour, spacing and 'is this the button?'. The designer draws. The developer guesses. Review is about pixels, not about whether the product is right. You think you are slow at building. You are slow at agreeing on what you already built.
Teams buy the wrong medicine. They see a slide with tokens, theming and 'governance', and draw a system project on top of a site that still changes its pitch every other week. Or they do the opposite: they have no contract, so every landing is a unique set. Both cost. One in theatre. The other in never being able to change a colour in one place.
It is also a performance and SEO question, not only an aesthetics question. Three different button implementations are three places you can forget focus, contrast and the state a crawler and a screen reader need. An honest set of components is boring — and that is why it holds. Variation you have not decided is the quiet way a Next.js site gets heavy and incoherent.
We write this because 'design system' has become a purchase you make before you have a sentence about what may vary. An honest setup is boring: a colour scale, a type scale, eight-point spacing, three button variants, and a name that may say no. Without that sentence you have Storybook. You do not have a system you can rebrand on.
What a design system actually is — and what it is not
A design system is the decisions the UI must keep, written so both Figma and the code can read them. Tokens are named values: colour, type, spacing, radius, shadow. Components are the few patterns you have said yes to. Documentation is the sentence that explains when you use the primary button, and when you do not. Ownership is who may add a fourth.
A component library is a folder of components. That can be right. It is not a system until tokens and the right to say no exist. You can have 40 components and still invent the 41st. You can have four and be done, if those four are the only ones you allow on a marketing site.
Storybook is a place to see the components. Useful when you have something to show. Theatre when you start with Storybook setup and 'addon-docs' before you have decided whether the button has a loading state. A gallery without a contract is how you get a pretty internal site production never uses.
And it is not a theme you buy. Tailwind, shadcn, Radix, Polaris, Carbon — they are starter kits and primitives. They give you a language. They do not give you your decisions. 'We use shadcn' is a dependency. 'We have three buttons, these tokens, and this person says no' is a system. The first you can install in an afternoon. The second you cannot buy.
What typically goes wrong when someone says design system
The first mistake is to start the system before the product has a face. You spend weeks on tokens and 'foundations' while the H1 and the offer still change. Then you build a library for a product you do not have. When the pitch lands, the components do not fit, and you have a system you are ashamed to open. Three honest blocks on an MVP beat a library you never dare delete.
The second mistake is Storybook as proof. You can show 20 states. Production uses three, and those three are copied into the pages anyway because 'it was faster'. A library pages do not import is an internal site. Measure the system on whether a new landing can be assembled from what you already have — not on whether the docs site is pretty.
The third mistake is to copy a large system's API and call it yours. Polaris is built for Shopify. shadcn is built for you to take a position. If you leave every variant in 'so we are covered', you have a catalogue nobody knows. A small team dies of choice. Cut until you can name the components without opening a folder.
The fourth mistake is to let every page be an exception. 'This campaign has to look like something else'. 'The footer on that page is special'. After half a year you have a system on paper and a unique site in production. The exception needs an owner and an end date — like a feature flag. Otherwise the exception has become the product.
Component library vs. design system — two different contracts
Component library
A folder you can import. Useful. Not a contract.
- Buttons, inputs, cards — code you can reuse
- Can start as shadcn, Radix or your own files
- No duty that pages actually use them
- Without tokens and a no, the 41st component is 'just this once'
Design system
The decisions behind the folder — tokens, owner, and what may vary.
- Named tokens Figma and CSS can both read
- Few variants, and a sentence about when you use which
- One person may say no to a new button
- A new surface is assembled from what you have — exceptions have an end date
How a small team starts — without buying a design-ops setup
Without this order you get either a gallery or no contract at all.
- 01
Write what may vary — in five lines
Not 'our brand'. 'One primary button, one secondary, one danger. One type scale. Spacing in eights. No new colour without an old one dying.' If you cannot say that, you are not ready for a system. You are ready for three honest blocks and a no to the fourth button.
- 02
Put tokens in one place the code actually reads
CSS variables, a small token object, or the theme Next.js and Tailwind can already point at. Mirror the names in Figma. If the designer says primary/500, the developer should not guess a hex. Two truths are how the rebrand becomes an archaeology project.
- 03
Build the few components the pages already repeat
Button, input, card, heading, listing. Not a modal system for a site without modals. Each component has the states you actually use — hover, focus, disabled, error. Skip 'we will make every variant now'. You can add. You cannot honestly delete 30 unused ones.
- 04
Give the system an owner and a no-sentence
Owner is a name, not 'design and frontend'. The no-sentence is: a new variant requires an old one to die, or you write why this surface is the exception and when the exception ends. Without a no the library is a suggestion.
- 05
Measure on the next page, not on the docs site
The next landing or the next app screen should be assemblable from what you have. If it cannot, you are missing a component — or you have said yes to an exception you should have said no to. Storybook can wait until the folder is actually imported.
“A design system pays off when you can change a colour in one place — and say no to the fourth button without a meeting.”
Next.js, marketing site and app — the same duty, different timing
A marketing site in Next.js can live a long time on an honest set: heading, section, card, form, CTA. That is a system even if you do not call it one. It becomes a problem when campaign pages start bringing their own buttons, or when WordPress leftovers and the new App Router page do not share tokens. Then it is not 'a bit of variation'. It is two brands on one domain.
An app next to the site — portal, checkout, admin — is usually when the system starts to pay. Two surfaces, two teams or two tempos, and without tokens you share you diverge in a month. Here a shared button and a shared type scale are not decoration. They are the only way a customer can believe login and the homepage are the same company.
An MVP of typically 8–14 weeks has to find the product. A full system project in that window is how you build a library for a UI you will scrap. Take three components you dare delete. Take tokens if you already know the app and the site must look alike. Do not take 'design-ops' because a slide said real teams have a system from day one.
If you are considering changing stack 'to get a system', be honest: you are changing the place the decision can sit. A WordPress theme with three child overrides is not a system either. A Next.js site with hexes in 20 files is the same mess with a different badge. Change stack if you also have other reasons. Do not change because a kit promised that components are free consistency.
What you should typically do in the situation you are in
The left is what you typically say. The right is the next step we typically recommend.
Situation
We want a design system before the site has a stable pitch
Next step
Three honest blocks and tokens you actually read. The library waits until you can name the pages it has to carry
Situation
We have Storybook, and production copies markup anyway
Next step
Import or delete. A gallery pages do not use is an internal site — not a system
Situation
Figma has tokens, and Next.js has hexes in CSS
Next step
One truth. CSS variables or a token object both can point at. The rebrand should be one file
Situation
We have a site and a portal, and they look like two companies
Next step
Shared button, type and colour first. That is usually when a small system pays
Situation
We copied shadcn and kept every variant 'to be safe'
Next step
Cut to what you show. A starter kit becomes yours only when you have said no to half of it
Checklist before you call it a design system
If you are missing several of these, the sentence is a slide — not a contract.
- Tokens have names, and the code reads the same names as Figma
- You can name your button variants without opening a folder
- A named person may say no to a new component
- The next landing can be assembled from what you have — or the exception has an end date
- Storybook, if you have it, shows what production imports — not a hope
- You have not started a system project to avoid deciding the pitch
Questions we hear again and again
When does a design system pay off for a small team?
When you have more than one surface — site and portal, site and app — or more than one person shipping UI, and you already know you must be able to change a colour in one place. It does not pay as a pre-project on an MVP still finding the pitch. Three honest components and tokens the code reads beat a library you build for a UI you will scrap. Take the system when the next page would otherwise become an exception. Do not take it because a slide said 'governance'.
Is a component library not the same as a design system?
No. The library is the folder. The system is the contract: tokens, few variants, and a right to say no. You can have a fine library and still invent the button on every landing. You can have a small system without Storybook if the pages actually import the same three components and Figma points at the same names. Call the folder a library until you have said what may not vary.
Should we use Storybook, shadcn or a large system like Polaris?
shadcn and similar primitives are an honest starter kit if you cut them. Polaris and other large systems are built for another company — useful to read, dangerous to copy at full width. Storybook is right when you have components production uses and several people need to see states. It is wrong as the first commit before you have a button you dare delete. Buy the pipe when the reading has become a product. Do not buy it to look like a design-ops team.
What do we do when Figma and the code have already drifted?
You do not start by drawing from scratch. You take the tokens production actually renders, give them names, and force Figma to point at them — or you take the Figma names and fix the code if the design is the truth you want to keep. One truth. Then the three components the pages repeat. Exceptions get a list and an end date. A new 'v2 design system' next to the old one is the fifth truth.
Can we wait with a system until we relaunch?
You can wait with the gallery. You should not wait with tokens if you already have two surfaces that must look alike after the relaunch. A relaunch without a contract is how you get a pretty v1 and a mess in v2. Put the names down before you redraw every page. Then the relaunch can change values in one place. Otherwise the relaunch is a new set of hexes in 20 files — again.
If the next landing needs a new button you dare not say no to
Let us separate tokens, folder and gallery.
Three components the code actually reads beat a Storybook you buy before you have a pitch.