The design system is a contract, not a component library

A component library is a set of buttons. A design system is a set of decisions about how a product should look and behave, written down so that people who were not in the room make the same choices.

The difference shows up about a year in, when the people who built it have left.

The failure mode is documentation drift

The component library keeps working. The system stops being used, because a new feature is built from a new pattern and nobody can tell whether it is a deliberate variation or a mistake.

Then you get two cards, three button styles, and four spacing values, all of which somebody chose on a Friday.

The failure is not technical. It is that the rules lived in people's heads and in a Figma file, and both left with them.

Write down the rules, not just the parts

A component entry should cover, at minimum:

• when to use it, and when not to
• the anatomy — which slots are required, which are optional
• the permitted variations
• the accessibility behaviour, already implemented rather than documented
• a correct and an incorrect usage example

The last one does more work than the rest combined. A single "do not do this" example resolves more ambiguity than three paragraphs of description.

Decide the variation policy explicitly

Every component accumulates variants, and without a rule the count grows monotonically.

A workable policy: variants are added only when the use case recurs across at least two features and cannot be solved with composition. Once added, a variant is a maintenance commitment and needs a named owner.

This is uncomfortable, because the immediate answer to a new request is a new variant. Resisting it is the whole job.

Semantic tokens before component decisions

If designers and engineers pick from the same named set — spacing, colour, type scale, radii, shadows — consistency follows without anyone policing it.

Use names that describe role rather than appearance. surface-raised and text-muted survive a rebrand; grey-100 and blue-600 become wrong the first time the palette changes and then get used anyway out of momentum.

Accessibility lives in the component

Every interactive component should ship with keyboard behaviour, focus management, and correct roles already implemented.

If accessibility is documented rather than built, every consumer decides whether to follow the documentation, and the answer is consistently no under deadline.

The components that handle focus correctly — dialogs, menus, comboboxes, date pickers — are the ones most often rebuilt badly. Getting them right once, centrally, is the highest-leverage work in the system.

Tokens and components are two different things

Tokens are the decisions. Components are the implementations. Conflating them causes real problems when a brand refresh arrives.

A token rename should touch the token file and nothing else, provided components consume semantic tokens rather than raw palette values. If renaming one colour requires touching forty components, the system is not actually tokenised.

Governance decides whether any of this survives

A system without an owner degrades. Assign responsibility for:

• approving new components and variants
• reviewing changes that affect existing components
• deprecating rather than silently changing
• auditing actual usage quarterly, since adoption is a fact rather than an intention

That last one is uncomfortable and necessary. Systems routinely have components nobody uses and variants that were added once for a feature that was cancelled.

The handover test

The system works if a designer who did not build it can compose a new screen from documented components and the result is consistent with everything else.

If that requires a walkthrough with the original authors, you have a library with good documentation and a system that lives in two people's heads. The first is useful. The second is a single point of failure with a resignation date.