Work / Note
A design system is not a component library
Components scale reuse. Principles, guidelines, and rules scale judgement. Only one of those survives contact with a case nobody anticipated — and every system meets one in its first month.
The situation
A large product has grown by accretion. Different teams have solved the same problems in different ways at different times, and the surface is now inconsistent in ways that are visible to the people who use it daily. The obvious remedy is a design system, and the obvious first move is to build a component library: a set of well-made, documented, reusable parts.
That work is genuinely valuable and it is not the hard part. The hard part shows up about a month in, when a team needs something the library does not contain.
The question
What should someone do when the system has no answer for their case?
This is not an edge case. It is the normal case. A component library can only encode decisions that were already made about situations that were already imagined. The interesting work always happens outside that boundary, and how a system behaves at its boundary determines whether it is adopted or routed around.
The move
Separate the layers by how much they constrain, and be explicit about which layer any given statement belongs to.
Principles are the small number of commitments that explain why the system is shaped the way it is. They do not tell you what to build. They tell you what to optimise for when you have to choose, and they are the only layer that helps in a situation nobody anticipated.
Guidelines are conditional advice. They describe what usually works and, more usefully, when it does not. A guideline that cannot say when to depart from it is a rule that has not admitted what it is.
Rules are the few things that are not open for negotiation, usually because the cost of inconsistency is borne by someone other than the person deciding — accessibility requirements, security behaviours, anything legal.
Components sit underneath all of that. They are the compiled output of decisions already made, and they are the layer people mistake for the whole.
What it produced
The immediate effect was a change in what documentation was for. A component page stopped being a specimen and started carrying the reasoning: what this is for, what it is not for, what to reach for instead when it does not fit, and which principle it is an expression of.
The second effect was less comfortable. Making the layers explicit exposed that several long-standing rules had no principle behind them. They were habits with institutional weight. Some survived the scrutiny and became guidelines. A few did not survive at all.
The third effect was that arguments got shorter. When a disagreement can be traced to a named principle, it becomes a discussion about whether the principle applies, which is tractable. Without that, the same disagreement is a contest of taste and seniority, which is not.
The point
What transfers
The reason this page exists, rather than the story that produced it.
- Any body of guidance benefits from being explicit about how binding each statement is. Most documents mix commitments, advice, and requirements in one voice, and readers cannot tell which is which — so they either follow all of it rigidly or none of it.
- The test of a system is its behaviour at the boundary, not its coverage inside it. Coverage is easy to demonstrate and easy to overvalue.
- A rule with no principle behind it is a habit that has acquired authority. That is worth finding out about, even though the finding out is unpleasant.
- Reuse and judgement are different goals and they need different artefacts. Building only for reuse produces a system that is excellent until the first novel case, and then silent.