The design system nobody reads

I have written three design systems. Two of them had beautiful documentation sites, with usage guidelines and do-and-do-not panels and a search box. Nobody read them. The third had almost no documentation and everyone used it correctly.

The difference was not discipline. It was that the third system made the wrong thing hard to type.

Documentation is a patch

Every guideline in a design system is a repair for something the API failed to communicate. Do not use the danger variant for non-destructive actions exists because the variant is a free-text string and nothing stops you. Only one primary button per view exists because the button does not know what else is on the page.

Some of those repairs cannot be made in code, and those are worth documenting. But most can. A variant that is an enum instead of a string. A spacing prop that only accepts scale steps. A colour token whose name is its role, so surface and ink cannot be swapped by someone who thinks a card should be a bit darker today.

Name things after their job

This is the single change with the highest return. When a token is called gray-100, every decision about where to use it is a judgement call, made fresh, by whoever is closest to the deadline. When it is called line, there is one right answer and it is in the name.

A system that has to be explained will be explained differently by every person who explains it.

Role names also survive a redesign. We moved an entire product from a cool grey palette to a warm one in a single afternoon, because nothing in the application referred to a colour — only to a role. The tokens changed. Nothing else did.

Ship the constraint, not the option

The hardest habit to break is generosity. You want the component to handle the case someone will inevitably have, so you add a prop. Then another. Eventually the component can express every layout in the product, which means it expresses none of them well, and the documentation grows to explain which combinations are actually supported.

The alternative is to say no and let people compose. Two rigid components that fit together are worth more than one flexible component with fourteen props, because the rigid pair cannot be assembled wrongly.

Where documentation still earns its place

Three things: the rationale behind a decision that looks arbitrary, the migration path away from something deprecated, and the examples that show composition rather than configuration. Everything else is a bug report about the API, written in prose, filed against your colleagues.