Layers of a component library
A good component library is organized in layers so simple parts compose into complex ones without circular knots.
- Primitives are unstyled building blocks like Box, Stack, and Text
- Components are styled and accessible parts like Button and Input
- Patterns combine components into flows like a search form or a data table
Each layer only depends on the layer below it, which keeps the dependency graph clean.
Public API discipline
A library lives or dies by its public contract. Expose props that describe intent, not implementation.
- Prefer variant and size props over a flood of boolean flags
- Forward refs and spread extra props so consumers can extend behavior
- Version with semantic versioning so breaking changes are explicit
Library layers
Distribution
Ship the library as a versioned package with tree shakeable exports so apps only bundle what they import. Document every component with live examples so adoption does not depend on reading source.
Key idea
Build a component library in layers with a small intentional public API so primitives compose upward and product teams adopt it without reading the internals.