What is a component library? What goes in one and how to judge it
The four layers inside a good library, where it ends and a design system begins, when to build your own, and a scorecard for judging any library.
According to the WebAIM Million 2026 report, 30.6% of the top million home pages contain an empty button, and 51% have a form input with no label. Those are not page-level mistakes. They are component mistakes, repeated every time someone pastes an icon button or a bare input into a new screen.
A component library is a versioned collection of reusable UI components, such as buttons, inputs, dialogs, and tables, each with a documented API, built-in states, and tests. It is the part of a design system that ships to production. Fix a bug in the library and you fix it on every screen that uses it.
Key takeaways
- A component library is code first: tested components with a stable API that product teams import instead of rebuilding.
- A good library holds four layers: primitives, composites, patterns, and the states each of them can be in.
- A design system is the larger whole of tokens, guidelines, process, and design files, and the component library is its production-facing half.
- Most teams get further by adopting a proven base and theming it than by building every component from scratch.
- You can judge any library in an afternoon by scoring API consistency, accessibility, theming, documentation, and tests.
What goes in a component library?
Most libraries grow by accident: a button, a modal, then three slightly different cards. A deliberate library is organized in layers, each with a different job.
| Layer | Examples | What it owns |
|---|---|---|
| Primitives | Button, Input, Checkbox, Badge, Avatar | One job each, keyboard and focus behavior, token-driven styling |
| Composites | Combobox, Date picker, Dialog, Data table | Coordination between primitives, focus management, ARIA relationships |
| Patterns | Sign-in form, Settings page, Empty state, Filter bar | Recommended arrangements of components for recurring tasks |
| States | Hover, focus, disabled, loading, error, empty, read-only | Every condition a component can be in, designed rather than improvised |
Composites are where libraries earn their keep. A combobox coordinates a text field, a popup list, the active option, and type-ahead, and the W3C's ARIA Authoring Practices Guide documents 30 patterns like this, each with its own keyboard and ARIA guidance. Getting them right once, in the library, is far cheaper than getting them right in every feature team.
Patterns are compositions with an opinion, like how a sign-in form is laid out. States are the layer most often missing. A button with no loading state invites someone to write their own spinner logic, and now you have two buttons.
Component library vs design system: what's the difference?
Nielsen Norman Group describes component libraries as collections that "house predetermined, reusable UI elements," and places them inside a design system alongside style guides and pattern libraries. That is the useful boundary. The design system makes the decisions: which colors, which spacing scale, which voice, how changes get approved. The component library carries those decisions out in code.
You can have a component library without a design system. What you lose is the reasoning: nobody can say why the primary button is that blue, so nobody knows whether a new shade is allowed.
Should you build or adopt a component library?
For most teams the answer is adopt, then own. An accessible combobox or date picker is a serious project on its own. Build from scratch only when:
- Your interface is genuinely unusual, such as a canvas editor or a trading terminal, and standard widgets don't fit it.
- You have a dedicated team that will maintain the library for years, not for a quarter.
- You have constraints no existing library supports, such as a framework nobody else ships for.
Otherwise, adopt. The real decision is what kind: a styled package you configure, headless primitives you style yourself, or source code you copy into your repository and own. Our companion guide to React component libraries compares the three.
How do you judge a component library's quality?
Demos are built to impress. To compare libraries, or audit your own, score five criteria from 0 to 2 points each. We call it the library quality scorecard: 10 points in total, and anything under 7 needs a plan before it becomes your foundation.
| Criterion | Scores 2 when | Scores 0 when |
|---|---|---|
| API consistency | Same prop names everywhere (size, variant, disabled) | Each component invents its own props, isDisabled here and disabled there |
| Accessibility | Keyboard paths, focus states, and ARIA documented per component | The word accessible appears only on the marketing page |
| Theming | Semantic tokens drive every color, radius, and spacing value, in light and dark | Hardcoded hex values, so theming means overriding CSS |
| Documentation | Every prop, variant, and state shown live, with usage guidance | A README and a prop table generated from types |
| Tests | Interaction and accessibility tests run in CI on every change | Snapshot tests only, or none |
API consistency is the criterion people underrate. Once you learn Button, you should be able to guess how Select takes size and disabled. Inconsistent APIs turn every component into a documentation lookup.
Accessibility needs more than an automated scan. Storybook's documentation says its accessibility addon, built on Deque's axe-core, catches up to 57% of WCAG issues automatically. The rest takes a keyboard and a screen reader, so check that focus order and keyboard behavior are documented for each component.
Theming decides whether the library ever becomes yours. Look for semantic tokens such as primary, muted, and destructive inside components, rather than raw palette names.
A component library you cannot theme is somebody else's design system with your logo on it.
Run the scorecard in one afternoon
Pick the three screens your product depends on most, then:
- Rebuild one of them with the candidate library and count the custom components you had to write.
- Tab through it without a mouse, and note every place focus disappears or lands somewhere unexpected.
- Change the primary color and the base radius in one place, and count how many components follow.
- Open the docs for the most complex component you used and check that every prop and state is covered.
- Read the tests for that component and the last three release notes.
The rebuild in step 1 tells you more than any feature matrix: it shows exactly where the library stops and your team's work starts.
Where Pegasus fits
Pegasus ships its component library on two synchronized surfaces: a Figma library of 1,540 components and matching React code in TypeScript, with the same component names, variant structure, and tokens on both. The code is built on shadcn/ui, Base UI primitives, recharts, and Tailwind CSS.
Against the scorecard: one token source (470 tokens for color, type, spacing, radius, and shadow, in light and dark modes) themes both the Figma variables and the code's theme object. Each component is documented with its anatomy, properties, and layout and spacing, and is built to WCAG 2.1 AA with keyboard paths, focus states, and contrast documented per component. Storybook carries stories and tests for the components. A local MCP server exposes the catalog to clients such as Claude Code and Cursor, so AI-generated pages reuse the library instead of inventing components.
Pegasus Lite, a free subset of the components, is enough to run the afternoon test above.
FAQ
What is the difference between a component library and a UI kit?
A UI kit is usually a set of design files: drawings of components in Figma or another design tool, with no production code behind them. A component library is code that ships in your product, with props, states, and tests. A kit helps designers mock up screens; a library is what engineers import. Some products pair the two with matching names and variants.
What should go in a component library first?
Start with the components on almost every screen: button, input, select, checkbox, dialog, toast, and table. Then add the composites that are hardest to get right, such as combobox and date picker, because that is where homegrown versions most often fail keyboard and screen reader users. Add patterns last, once you see which layouts teams keep rebuilding.
Is a component library the same as a design system?
No. A component library is the coded set of reusable components. A design system includes the library plus the decisions behind it: design tokens, usage guidelines, content standards, design files, and the process for changing any of them. You can adopt a component library in a day; a design system is something your team maintains for years.
Sources
- The WebAIM Million 2026, WebAIM (2026)
- Design Systems 101, Nielsen Norman Group (2021, reviewed 2026)
- Patterns, ARIA Authoring Practices Guide, W3C WAI (2026)
- Accessibility tests, Storybook docs (2026)
One system. In Figma and in code.
Pegasus ships 1,540 components, 470 tokens, matching React code, Storybook, and a local MCP server. $149, one-time.
Get the full system