Design System vs Component Library
Tiffinbox's web engineers publish a package called @tiffinbox/ui, with thirty React components, and announce: "We have a design system!" Six months later the components are everywhere, but used in strange ways. A red "danger" button sits on the checkout screen as the main call to action, and three screens space the same cards in three different ways. The code was fine. Something else was missing.
The rule
A component library is the code; a design system is the code plus the why.
A component library is a collection of built, reusable interface components that a team installs and uses: a button, a text field, a modal. It answers how: which props a component takes and what it renders.
A design system contains a component library, often several, and much more:
- Foundations: the named decisions (colour, type, spacing) that the components are made of.
- Design assets: the same components in the design tool, for designers.
- Guidelines: when to use each component, when not to, with examples.
- Patterns: proven ways to combine components for common tasks.
- Content guidance: voice, tone and writing rules.
- Process: how to ask for changes, contribute and release.
The library happily renders this:
import { Button } from "@tiffinbox/ui";
<Button variant="danger">Place order</Button>Nothing in the code is broken. Only a guideline, "the danger variant is for actions that delete or cannot be undone", tells you it is the wrong choice.
Open any public design system, such as Material Design, Carbon, Polaris or the GOV.UK Design System, and you will see the same shape: the component list is one section among foundations, writing guidance, patterns and notes on contributing.
Two consequences follow. You can have a component library without a design system; installing an open-source UI package gives you exactly that. And one design system can have several libraries: Thali has a React library for web, one for iOS and one for Android, all built from the same decisions.
The shortcut
Ask of any question: is it "how" or "when and why"? The library answers how. The rest of the system answers when and why.
"What props does Card accept?"
A how question. The component library's API reference answers it.
Drills
Answer fast — trust the rule.
A team installs an open-source React UI package. What do they have now?
Which of these belongs to the design system but not to the component library?
Thali ships components for web, iOS and Android. How many design systems is that?
The library renders <Button variant="danger">Place order</Button> without any error. What catches the mistake?
Remember
- A component library is the code; a design system is the code plus the why.
- Shortcut: "how" questions go to the library; "when and why" questions go to the rest of the system.
- Trap: publishing a package of components and calling the job done.