A component library is easy to start and hard to keep. The first twenty components take a quarter; the next two years are spent on consistency, migration and the slow accumulation of exceptions. Treating the system as a product — with users, a roadmap and a support burden — is what changes the outcome.
1. The design system is a product, not a side project
The users are product engineers and designers. Their “jobs to be done” are concrete: build a form that is accessible without researching ARIA, ship a table that does not fall apart at 200 rows, and change a brand colour without editing forty files.
That framing changes priorities. Adoption is the success metric, not the number of components. A small system that everyone uses beats a comprehensive one that teams route around. Fund maintenance explicitly: if nobody owns upgrades, the system will be abandoned the first time a framework major lands.
2. Tokens are the real public API
Components are the visible surface, but tokens are what make the system configurable without forking it. Define them by intent, not by appearance:
/* Good: semantic, themeable */
--color-surface-default: #ffffff;
--color-surface-raised: #f6f7fb;
--color-text-primary: #101828;
--color-text-muted: #536076;
--color-action-primary: #6d00b3;
--space-inline-md: 0.75rem;
--radius-control: 6px;
/* Avoid: literal names that block theming */
--purple-500: #6d00b3;
--gray-200: #f6f7fb;
Keep the token set small and stable. A theme should be a remapping of semantic tokens, not a parallel stylesheet. Publish the token contract and treat renames as breaking changes; teams will hard-code the values anyway, but at least the intended path is clear.
3. Design component APIs for the common case
A good component API makes the right thing easy and the wrong thing possible only with effort:
- Prefer composition over configuration. Slots or content projection age better than a
boolean for every layout variant. A component with
hasHeader,hasFooter,isCompactandisBorderedis four components wearing a trench coat. - Use a small set of named variants for visual intent, and let layout be the consumer’s job.
- Make the common path the default. Accessible labels, sensible keyboard behaviour and correct semantics should not require extra props.
- Avoid leaking implementation types. If the public API exposes a third-party object, that library now owns your upgrade path.
- Document the contract — props, events, slots, states and keyboard behaviour — in the same repository as the code.
4. Accessibility belongs in the component, not the page
Every product team re-implementing focus management is a systemic bug. Components should own:
- Semantic roles, accessible names and state announcements.
- Keyboard interaction and focus order, including focus return when a dialog closes.
- Visible focus styles that meet contrast requirements.
- Disabled, loading, error and empty states that are still understandable to assistive technology.
- Reduced-motion behaviour and target sizes that meet WCAG 2.2.
Test these behaviours in the component library, not only in the consuming application. A dialog that traps focus correctly in the design-system test suite is fixed once for every product. See the WCAG 2.2 component checklist for the specific checks.
5. Documentation that answers real questions
Generated prop tables are necessary but not sufficient. The pages teams actually need are:
- When to use this component and, more usefully, when not to.
- Copy-paste examples for the 80% case, with realistic content rather than “Lorem ipsum”.
- Accessibility notes: keyboard map, required labels, known limitations.
- Do/don’t examples that show the visual consequence, not just rules.
- Migration notes for every breaking change, with a codemod where possible.
Keep the documentation next to the code and run it in CI, so it cannot describe a component that no longer exists.
6. Versioning and deprecation without drama
Semantic versioning is a promise, and design systems break it casually. A colour change is visual, not breaking in API terms, but it can still break a product’s contrast or brand review. Be explicit about what counts as breaking:
| Change | Version | What teams need |
|---|---|---|
| New optional prop or component | Minor | Release note and example |
| Token value change with visual impact | Minor or major, documented | Screenshot diff and migration note |
| Renamed token or removed prop | Major | Deprecation period, codemod, migration guide |
| Behaviour change in a form control | Major | Explicit review with consuming teams |
Deprecate before removing. Keep at least one minor release with a runtime warning and a documented replacement. Publish a support window so teams can plan upgrades alongside product work rather than discovering them during a release crunch.
7. Measure adoption, not inventory
Useful signals:
- Percentage of product screens using system components for primary flows.
- Number of local forks or overrides, and why they exist.
- Time to build a standard form, table or dialog with the system versus without it.
- Accessibility defects traced back to components, and time to fix once centrally.
- Upgrade lag: how long after a major release consuming teams move.
Review these quarterly with the product teams. If adoption is low, the answer is usually not more documentation; it is that the component does not fit the job. Fix the API.
8. Governance without bureaucracy
A small group should own the contract, but contributions should be welcome. A workable model:
- An RFC for new components and breaking API changes, with a short template and a stated decision window.
- A weekly or biweekly review that includes design and engineering, so visual and technical decisions happen together.
- Clear ownership for each component, including accessibility and documentation.
- A rule that a component ships with tests, docs and an example, or it does not ship.
9. Start smaller than you want to
The highest-value first release is usually tokens, typography, buttons, form controls, dialog, table and a layout primitive — plus the documentation and release process. Those cover most screens. Add components when a second team needs them, not when they look good in a catalogue.
- Semantic tokens with a documented, stable contract.
- Composition-based APIs and accessible defaults.
- Tests for keyboard, focus, announcements and states.
- Docs for when to use, when not to, and how to migrate.
- Deprecation policy and a support window.
- Adoption measured by real screens, not component count.
- Explicit ownership and funding for maintenance.
A design system earns its place by removing decisions, not by adding a catalogue. When teams reach for it because it is the fastest way to build something correct, it will survive the next redesign, the next framework upgrade and the next reorganisation.
Related reading: where the shared layer belongs in a distributed frontend, in Where micro-frontend boundaries should go.