Building reusable component systems

A component library succeeds when teams reach for it first because it is the fastest way to build something correct. It fails when it is a set of rigid widgets that every team wraps, forks or works around. The difference is mostly in tokens, APIs and documentation.

Tokens come first

Design tokens are named decisions: colours, type sizes, spacing, radii and motion. Components use tokens and never raw values, so a change to a decision happens in one place.

Name tokens by role rather than appearance. color-fg-secondary survives a rebrand and a dark mode; gray-600 does not.

:root {
  --fg: #111214;
  --fg-secondary: #55585e;
}
@media (prefers-color-scheme: dark) {
  :root {
    --fg: #edede8;
    --fg-secondary: #a3a5a9;
  }
}

Component APIs

Good component APIs are small and hard to misuse:

• Variants over style overrides. variant="secondary" keeps decisions in the library; a className that overrides colours moves them into every product.
• Semantic props. Separate what something is from how it looks: a heading's level and its visual size are different props.
• Composition over configuration. A Card with slots is easier to extend than one with twenty boolean props.
• Accessibility built in. An icon-only button that requires a label prop cannot ship without an accessible name.

Documentation is part of the product

Every component needs a live example of each state — default, hover, focus, disabled, loading, error — and guidance on when not to use it. If the documentation is out of date, teams stop trusting the library.

Versioning and change

Treat the library like any other dependency teams rely on: semantic versioning, changelogs, deprecation warnings before removals, and codemods for large changes.

Signs a system is working

1. New screens are built mostly from existing components.
2. Teams contribute fixes back instead of forking.
3. Visual and accessibility bugs are fixed once, in one place.