What Is a Component Library in Design? Definition, Examples and How It Differs From a Design System

by | Nov 17, 2026 | Uncategorized | 0 comments

Quick answer: what is a component library in design?

A component library is an organised collection of reusable interface elements (buttons, cards, inputs, modals, navigation bars) that a team builds once, documents, versions and then reuses across every screen and product. In design tools it lives as a set of published, named components. In code it lives as a package of UI components that developers install and import.

Put simply: a component library is the shared parts bin of a product team. It is not the whole design system, and it is not the same thing as a free UI kit you downloaded off the internet. The difference between those three things is exactly where most teams get confused, so let’s settle it properly.

The longer definition (and why the word “component” matters)

A component is a self-contained chunk of user interface that has a clear job, a defined set of options and a predictable behaviour. A Button is a component. A Price card is a component. A Text field with label, helper text and error state is a component.

What turns a pile of components into a library is four things:

  1. Curation: someone decided what goes in and what stays out.
  2. Naming and organisation: components are grouped and named in a way other people can search.
  3. Documentation: each component explains its purpose, its variants, its props and when not to use it.
  4. Versioning and distribution: there is a single source that gets published, updated and consumed by everyone else.

Remove documentation and versioning and you no longer have a library. You have a folder.

Design-side vs code-side component libraries

The same phrase is used by two different audiences, which is another reason for the confusion.

Aspect Design component library Code component library
Lives in Figma, Penpot, Sketch, Framer A package (React, Vue, Web Components, SwiftUI, Compose)
Unit of reuse Published component with variants and properties Exported component with props and types
Distributed by Library publishing and update notifications Package registry install and version bump
Browsed through Assets panel, cover pages, documentation frames A workshop environment such as Storybook
Breaks when Designers detach instances and improvise Developers fork components into one-off local copies

A healthy team keeps both in sync: same names, same variants, same states. When the Figma button has a loading state and the React button does not, the library has already started to drift.

ui design components figma

Concrete examples: what a component actually looks like

Abstract definitions are easy to nod along to and hard to apply. Here are three components spelled out the way they should appear in real documentation.

Example 1: the Button

The button is the component everyone builds first and almost everyone builds badly. A properly specified button is not one shape, it is a small matrix.

Property Values Notes
Variant Primary, Secondary, Tertiary, Destructive, Ghost One primary action per screen region
Size Small, Medium, Large Minimum 44px touch target on mobile
State Default, Hover, Focus, Active, Disabled, Loading Focus ring is non negotiable for accessibility
Icon None, Leading, Trailing, Icon only Icon only requires an accessible label

That is 5 x 3 x 6 x 4 possible combinations. You do not draw them all. You build one component with four properties, which is precisely the point of a component library: combinatorial coverage from a single source.

Example 2: the Card

A card is a container, and containers are where libraries usually get sloppy. A well-defined card documents:

  • Slots: media area, eyebrow, title, body text, metadata row, action area.
  • Which slots are optional and what the card looks like when they are empty.
  • Elevation and border treatment (flat, outlined, raised) and when each is used.
  • Interaction model: is the whole card clickable, or only the title link? Pick one and stick to it, because mixed behaviour is a known accessibility trap.
  • Responsive behaviour: stacking order and image ratio at each breakpoint.

Typical card family in a mature library: Card/Content, Card/Product, Card/Stat, Card/Empty state. Four distinct components sharing one base, not fifteen unrelated rectangles.

Example 3: form elements

Forms are the real stress test of a component library because they carry data, validation and error handling. A form input component should ship with:

  1. Label (always visible, placeholders are not labels)
  2. Required or optional indicator, applied consistently across the product
  3. Helper text slot
  4. Error message slot with an error state style
  5. Prefix and suffix slots (currency symbol, unit, inline button)
  6. Disabled and read-only states, which look different and behave differently
  7. Character counter where relevant

The same anatomy then repeats across Select, Textarea, Checkbox group, Radio group, Toggle, Date picker and File upload. When that anatomy is shared, users learn your form logic once. When it is not, every form feels like a new product.

ui design components figma

Component library vs UI kit vs design system vs pattern library

This is the comparison most articles skip, so here it is in one place.

  UI kit Component library Pattern library Design system
What it is A visual starter pack of screens and elements Reusable, documented, versioned UI parts Recurring solutions to recurring UX problems The full ecosystem: principles, tokens, components, patterns, governance
Scope Visual only Visual plus behaviour and code Composition and flow Everything, including process and people
Versioned? Rarely Yes, mandatory Sometimes Yes, across all layers
Has an owner? No Usually a small team Usually UX leads Yes, with a formal contribution model
Example artefact A downloaded Figma file of dashboard screens Published Figma library plus a package in Storybook “How we do empty states and onboarding” A documentation site with tokens, components, patterns, a11y rules
Relationship Can become a library if curated A subset of a design system Sits above components Contains all of the above

The one-line version worth remembering: every design system contains a component library, but a component library on its own is not a design system. The missing pieces are design tokens, written principles, accessibility standards, content guidelines, contribution rules and someone accountable for maintaining it all.

Components vs patterns, in one sentence each

  • Component: a thing you place (a button, a toast, a tab bar).
  • Pattern: a way you combine things to solve a user problem (a multi-step checkout, a destructive confirmation flow, a search and filter layout).

Figma naming conventions that actually scale

Naming is 80% of whether a library gets used, because in practice people find components by typing in a search box. Figma builds its menu structure from forward slashes in the component name, so the name is the information architecture.

The base pattern

Category / Component / Subcomponent

Real examples from well-structured libraries:

  • Actions / Button
  • Actions / Icon button
  • Forms / Input / Text field
  • Forms / Input / Select
  • Forms / Checkbox
  • Surfaces / Card / Product
  • Navigation / Tabs
  • Feedback / Toast
  • Data display / Table / Row

Properties instead of more slashes

Everything that varies should be a component property, not a new component name. Inside Actions / Button you then have:

  • Variant: Primary | Secondary | Tertiary | Destructive
  • Size: SM | MD | LG
  • State: Default | Hover | Focus | Disabled | Loading
  • Icon left: boolean
  • Icon right: boolean
  • Label: text property

Rules that keep this clean over time:

  1. Sentence case for names, lowercase for property values, and never mix the two conventions mid-library.
  2. Property names must match the code props. If the developer writes variant="destructive", the Figma property should say Destructive, not Danger.
  3. Prefix private building blocks with a dot or underscore (.Button base, _Field wrapper) so they stay out of the published assets panel.
  4. No dates, no initials, no “v2 final” in component names. Version history belongs in the release notes, not the layer name.
  5. One canonical name per concept. Decide once between Snackbar and Toast, Modal and Dialog, Chip and Tag. Write the decision down.

Supporting structure

Alongside the components themselves, a usable Figma library has: a cover page, a page per category, a “Playground” page for testing instances, a “Deprecated” page for components on their way out, and documentation frames placed next to each component instead of in a separate file nobody opens.

ui design components figma

How teams document a component

A component without documentation gets reinvented within a month. The documentation template below covers what designers, developers and content writers each need.

Section What it answers
Purpose What problem does this component solve, in one or two sentences
Anatomy Labelled diagram of every part and which ones are optional
Variants and props Full list with default values and allowed combinations
States Default, hover, focus, active, disabled, loading, error, empty
Do and Don’t Visual examples of correct and incorrect usage
Accessibility Keyboard behaviour, roles and labels, contrast, focus order
Content guidelines Label length, capitalisation, tone, truncation rules
Code snippet Copy-paste usage example with the real import path
Related components What to use instead when this one is the wrong fit
Status Draft, stable, deprecated, plus the version it landed in

How teams version a component library

Versioning is what separates a library from a shared folder. The standard approach is semantic versioning, written as MAJOR.MINOR.PATCH.

  • PATCH (1.4.2 to 1.4.3): a bug fix with no API change. A focus ring colour corrected, a 1px alignment fix.
  • MINOR (1.4.3 to 1.5.0): something added, nothing broken. A new Ghost button variant, a new Card/Stat component.
  • MAJOR (1.5.0 to 2.0.0): a breaking change. A prop renamed, a variant removed, a component retired.

The deprecation workflow

Nothing should ever vanish overnight. The sequence used by mature teams:

  1. Mark the component as Deprecated in the documentation and add a console warning in code.
  2. Rename it in Figma with a [Deprecated] prefix and move it to the Deprecated page so it stops appearing first in search.
  3. Publish a migration note: what replaces it and how to swap, ideally with a codemod or a Figma swap instruction.
  4. Keep it alive for at least one release cycle, typically a quarter.
  5. Remove it in the next MAJOR release and record the removal in the changelog.

Keeping design and code versions aligned

Two practical habits make a measurable difference:

  • Write a human-readable changelog for every publish, with the version number, the date, and a plain sentence per change. Figma’s publish description field is the right place for the design side.
  • Run a design and engineering release review on a fixed cadence (every two weeks works for most teams) where new components are accepted, deprecations are announced and drift is caught early.
ui design components figma

When a component library is worth building (and when it is not)

Build one when

  • You have more than one product surface, or more than one squad shipping UI.
  • The same screen elements are being rebuilt repeatedly with small inconsistencies.
  • Design QA keeps catching the same spacing, colour and state mistakes.
  • Accessibility fixes have to be applied in a dozen places instead of one.
  • Onboarding a new designer or developer takes weeks because nothing is documented.

Skip it (for now) when

  • You are a solo builder shipping a first version and the interface is still changing weekly.
  • The product has fewer than a handful of screens.
  • Nobody can own maintenance, in which case the library will rot and become a liability.
  • A well-maintained third-party library already covers your needs and your brand can live inside its theming layer.

A reasonable middle path: start with design tokens and three or four components that appear on every single screen (button, input, card, typography). Grow from real usage, not from an imagined inventory.

Six mistakes that kill component libraries

  1. Building for the library instead of the product. If no screen uses it, it should not exist yet.
  2. Variant explosion. Eleven button variants means nobody knows which to pick. Three or four is usually plenty.
  3. Hardcoded values instead of tokens. Without tokens, a rebrand or a dark mode becomes a manual rebuild.
  4. No contribution path. When requesting a change is harder than detaching an instance, people detach.
  5. Documentation that lives somewhere else. If it is not one click from the component, it is not read.
  6. Treating accessibility as a later phase. Focus states, contrast and keyboard behaviour belong in the component, not in a backlog ticket.
ui design components figma

A seven-step starting plan

  1. Audit. Screenshot every button, input and card currently in production. The duplication will make the business case for you.
  2. Define tokens. Colour, type scale, spacing scale, radius, elevation, motion. Name them by role (surface-default, text-muted) rather than by appearance.
  3. Agree on naming. Write the convention on one page and get both designers and developers to sign off before anything is published.
  4. Build the core five. Button, text field, card, modal, and your most used navigation element.
  5. Document as you build, using the template above. Documentation written later is documentation never written.
  6. Publish version 1.0.0 in both design and code, on the same day, with matching release notes.
  7. Set up governance. Who approves additions, how requests are submitted, what the review cadence is, and how deprecations are communicated.

FAQ

What is a component library in design, in one sentence?

It is a curated, documented and versioned collection of reusable interface elements such as buttons, cards and form fields, shared by designers and developers so the same UI is built once and reused everywhere.

Is a component library the same as a design system?

No. A component library is one part of a design system. The design system also includes design tokens, principles, accessibility standards, content guidelines, patterns and a governance model that says who maintains what.

What does a design system consist of?

Typically six layers: design principles, design tokens, a component library, UX patterns, content and accessibility guidelines, and the governance plus documentation that keeps all of it current.

What is a component, with an example?

A component is an isolated, reusable chunk of interface with defined options. Example: a Text field component with a label, helper text, optional prefix icon, and states for default, focus, disabled and error. You place it a hundred times and change it in one place.

What is a component library in Figma specifically?

A Figma file containing published components with variants and properties, shared across a team or organisation. Other files subscribe to it, receive update notifications, and swap instances when a new version is published.

How do I create a React component library?

At a high level: scaffold a package with a bundler, write each component with typed props that mirror the design properties, wire your design tokens in as CSS variables or a theme object, document every component in a workshop tool such as Storybook, add accessibility and visual regression tests, then publish to a registry with semantic versioning and a changelog.

What is the difference between a UI kit and a component library?

A UI kit is a visual starter pack: screens and elements you can copy. A component library is a maintained product with naming rules, documentation, versions and an owner. A UI kit can become a component library, but only after it is curated, documented and versioned.

Pattern library vs design system: what changes?

A pattern library documents repeatable UX solutions (checkout flows, empty states, filtering). A design system contains the pattern library, the component library and everything else needed to build consistent products end to end.

Key takeaways

  • A component library is a curated, documented and versioned set of reusable UI parts, not a folder of screens.
  • It is a subset of a design system, which adds tokens, principles, patterns, accessibility rules and governance.
  • Buttons, cards and form elements are where the value shows up first, because they appear on nearly every screen.
  • Naming is architecture: use Category / Component / Subcomponent and push variation into properties that match your code props.
  • Version it like software: semantic versioning, written changelogs, and a deprecation path that gives teams at least one release cycle to migrate.

Recent Posts

No Results Found

The page you requested could not be found. Try refining your search, or use the navigation above to locate the post.

Latest Projects

Subscribe

Follow Us