Component-Driven Development
The principles behind building interfaces as a system of components rather than a collection of pages.
The page model vs the component model
Traditional web development builds pages. A page is a complete, self-contained document that contains everything needed for a specific view. Components are assembled as needed for each page. In this model, consistency between pages is maintained by the developer's discipline — and it erodes over time as the codebase grows and the team changes. Component-driven development inverts this: the primary unit of development is the component, and pages are compositions of components. Consistency is structural rather than disciplinary.
What makes a good component boundary
A component boundary is correct when the component does one thing and does it completely. A Button component handles all button states and variants. A Card component handles all card content and layout. The test for a correct boundary is the reuse test: can this component be used in a context different from the one it was built for, without modification? If the answer is no, the component contains context-specific logic that belongs in its parent.
The token dependency
Component-driven development only produces a coherent system when the components share a common token layer. A Button component that hardcodes its background colour to '#2563EB' is not part of a system — it is a standalone artefact. A Button component that uses 'var(--color-primary)' as its background inherits from the token layer and participates in the system. When the token layer changes, the button changes with it.
Documentation as a first-class concern
A component library without documentation is a collection of code. Documentation — what the component does, what its props are, what its variants look like, what it should not be used for — is what turns a collection of code into a shared language. Write documentation at the time you write the component, not afterward. Documentation written after the fact describes what the component does. Documentation written during development records the decisions behind it, which is more valuable.
When to reach for a component
Not everything should be a component. A pattern that appears in one place is a layout. A pattern that appears in two places is a coincidence. A pattern that appears in three or more places, or that you anticipate needing in multiple contexts, is a component candidate. Extracting components prematurely creates abstraction overhead without reuse benefit. The right time to extract a component is the second or third time you find yourself rebuilding the same structure.
Field Notes in your inbox
Practical observations on design systems, component architecture, and UX methodology. No promotional content. Published when there is something worth saying.