Do I need a design system, a style guide, or just a component library?

The three are often used interchangeably, which is why people buy the wrong one. They differ in what they contain and, more importantly, in what enforces them.

A style guide is a document. It describes the intended visual language — colours, type sizes, spacing, logo usage, tone — in a form a human reads and then applies by hand. Nothing stops someone ignoring it.

A component library is code. It is the set of built, reusable pieces the site is assembled from: buttons, cards, form fields, navigation, page sections. It is enforced by the fact that building a page means using it. Deviating costs more effort than complying.

A design system is a component library plus the layer above and the layer below it: design tokens as the single source of values, documented usage rules and decision criteria, versioning, and a contribution process for adding or changing components. It exists to keep multiple people making consistent decisions without asking each other.

• Style guide: a document, enforced by discipline, describes intent.
• Component library: code, enforced by the build, produces the interface.
• Design system: tokens plus components plus documented rules and a change process, enforced by the build and by process.

The purchase price is not the interesting number. The interesting number is what it costs to stay true twelve months after launch, and here the three diverge sharply.

In our projects, standalone style guides rot within two quarters. The mechanism is always the same: someone needs a page the guide does not cover, they invent a spacing value or a slightly different blue, the page ships because it looks fine in isolation, and the document is now describing a site that no longer exists. Nobody is at fault. The document had no way to object. Maintaining it properly means someone reviewing every change against a PDF, which is a job nobody has ever actually been given.

A component library survives because the code is the source of truth. There is no gap between the description and the artefact — the component is the description. Its maintenance cost is real but bounded: you pay when you need a component that does not exist yet, and that cost is work you would have done anyway. In our experience a library of twenty to thirty components covers a marketing site of forty pages, and a typical year adds two or three new components rather than a rewrite.

A design system costs more than either, and the cost is ongoing rather than up front. Tokens have to be kept in sync with the code. Documentation has to be updated when a component changes, or the documentation becomes a style guide and starts rotting. Someone has to own the decision when two teams want the same component to behave differently. That is a recurring commitment of a few hours a month at minimum, and it only makes sense if it saves more time than it consumes.

The table below compares the three on the dimensions that decide the choice: what enforces them, how long they survive unattended, what they cost after handover, and the team size at which they start to make sense.

Read the enforcement column first. It predicts every other column.

• Style guide — Form: document. Enforced by: human discipline. Survives unattended: about two quarters. Post-handover cost: low to produce, high to police. Makes sense when: you have a brand but no website team, or you need something for print and external agencies.
• Component library — Form: code plus a rendered index of the components. Enforced by: the build. Survives unattended: as long as the site runs. Post-handover cost: only the work of adding components you needed anyway. Makes sense when: one site, one to two people changing it.
• Design system — Form: tokens, components, documentation, versioning, contribution rules. Enforced by: the build plus process. Survives unattended: documentation drifts within a quarter if unowned. Post-handover cost: a few hours a month of genuine ownership. Makes sense when: multiple sites or products, or three or more people making changes each month.

Count the people who changed something visual on your site in the last month — not who could, who did. If the answer is one or two, you need a component library. If it is three or more, or if those people work in different teams, a design system starts paying for itself.

The reason is that a design system’s real product is not consistency, it is not having to ask. One person building pages holds the rules in their head and stays consistent for free. Two people can settle a question in a message. Five people across marketing, product and an external contractor cannot, and the cost of them each deciding independently is exactly what documented tokens and usage rules remove.

The same test applies to surface count. One marketing site needs a library. A marketing site plus an app plus a customer portal that must all look like the same company needs tokens sitting above the code, because otherwise each surface drifts on its own timeline.

A worked example from our own projects: a forty-page site, one marketing manager publishing and editing, an occasional contractor. We shipped twenty-four components, tokens for colour, type and spacing baked into the code, and a components page showing every variant in use. No separate documentation site, no contribution process, no versioning. Eighteen months later the site is still consistent, because the only way to build a page there is to use what exists. A design system would have added several thousand pounds of documentation for one person to read.

Every Glasspage redesign ships on our own design system, so what you receive is a component library instantiated with your tokens: the coded components your site is built from, the token values behind them, and a page that renders every component and variant so you can see what exists without reading code.

We decline to produce a standalone style guide as a deliverable on most projects. Not because guidance is worthless, but because a document that duplicates the code creates two sources of truth and the code wins every time. If you need something for print, packaging or an external agency who cannot use your components, that is a brand guideline and a fair thing to buy — it just is not what keeps a website consistent.

We also decline to build a full design system for a single site with one or two editors. The documentation layer, the contribution process and the versioning are real work, and on a small team they are read once and then go stale. We would rather spend that budget on more components, because components are the part that still works when nobody is looking after it.

Where a client genuinely needs the design system layer — several surfaces, several teams, changes arriving weekly from different directions — we build it as a follow-on once the library is proven in production. Documenting rules before you know which rules the site actually needs is how you end up documenting the wrong ones.

A component library built properly is the first two thirds of a design system, so upgrading is additive rather than a rebuild. That is the practical argument for starting with the library even when you suspect you will need more later.

The prerequisite is that values live in tokens from day one. If your components reference a named colour and spacing scale rather than hard-coded values, adding a documentation layer, versioning and a contribution process is work you bolt on top. If they contain literal hex codes and pixel values scattered through the code, you pay for extraction first, and in our experience that is the single most expensive retrofit on an otherwise healthy codebase.

The trigger to upgrade is a specific event, not a date: the second time two people independently build the same thing differently, or the first time a second surface has to match the first. Until one of those happens, the documentation you would write has no reader.