Maintaining a small design system

Most teams that ask for a design system are asking, really, for the end of an argument. The hope is that a well-defined set of components and tokens will let everyone stop relitigating button radii in every pull request, and get on with the work. The hope is mostly justified — but only if the system itself doesn't quietly become the new argument.

We've worked on enough of these now to have a few habits that seem to hold up. None of them are universal; they all assume a small team and a system that's actually used.

Ship it half-built

The version-one design system that tries to cover everything is the one that gets quietly abandoned. We try, instead, to ship a system that covers the next two months of product work, and nothing else. Eight components, four tokens, one documentation page. The rest gets added in response to real demand, by the people writing the product.

This is harder than it sounds. Every team we've worked with has had a strong urge to predict — to build the modal variant they'll need in Q3, to spec the chart palette before the first chart. We've come to think of that urge as a small-but-real risk. Speculative components decay faster than the product around them, and tend to get rebuilt anyway when their first real use arrives.

Treat the system like a product

This is the most common piece of advice in this corner of the industry, and it's the one we've found most useful in practice. The system needs an owner, a backlog, a changelog, a sense of who its users are. Without those, it drifts.

What "owner" means in a small team is sometimes one person, sometimes a rotating role, sometimes a Friday afternoon. The shape matters less than the existence: someone, regularly, is looking at the system and asking whether it still serves the work. Without that loop, a system slowly fills with components that no one would build today.

Documentation is editorial

Most design system docs read like a parts catalogue: this is what it looks like, here are the props. The components people actually understand are the ones whose docs answer a different question — when do I use this, and what does it cost me. The shift from descriptive to editorial documentation has, in our experience, the single largest effect on whether a system gets used the way it was meant to.

We try to keep examples short and the prose shorter. Two paragraphs and a small set of dos and don'ts beats a long specification every time. If the right usage isn't clear in two paragraphs, the component is usually too generic.

Subtract on a schedule

Design systems grow naturally. They shrink only on purpose. We try to take an afternoon every quarter to look for things to remove — components that no one's used in six months, tokens with one consumer, doc pages that contradict the code. Most of those afternoons end with two or three deletions, which sounds like nothing and turns out to be a lot. A system that subtracts on a schedule stays inhabitable.

Keep it boring

The temptation, especially in year two, is to add the clever thing — the polymorphic component, the runtime theme switcher, the cross-platform tokens pipeline. Sometimes those are warranted. Mostly they aren't. Most of the value of a design system comes from the dullest parts of it: the small set of well-named primitives, used everywhere, that turn the daily product work from a hundred small decisions into ten.

If your system is boring and well-used, you're doing it right. The interesting work, in the end, happens in the product on top of it.