A design system is a promise, not a library

For a long time I measured a design system by how many components were in it. More components felt like more progress. I was wrong about that.

A design system is not a library you fill up. It is a promise you make to everyone building the product. The promise is simple. If you use these pieces, the thing you ship will look right, behave right, and fit with everything else. The moment that promise breaks on a real page, the whole system starts to lose trust.

The number that actually matters

The question I ask now is not how many components we have. It is how many of our most used screens are actually built from them. A beautiful system that your busiest pages ignore is just a folder of nice ideas.

At ChartRequest the platform had grown for years, and every team had quietly built its own version of the same table, the same dialog, the same form. On paper we had patterns. In practice the product felt like it was made by five different companies. Fixing that was less about drawing new components and more about getting the real pages to adopt the shared ones.

Adoption is a design problem too

I used to think adoption was someone else's job. Ship the component, write the docs, move on. That never worked. People reach for the shared piece only when it is genuinely easier than rolling their own.

So I started treating the developer as a user. Is the component easy to find? Does it handle the messy edge cases they will actually hit? Does it save them time on day one? If the answer is yes, adoption takes care of itself. If it is no, no amount of documentation will save it.

Restyle in place before you reinvent

One thing I learned the hard way. On daily use tools, do not reorganise everything just because you can. The people who live in those screens have muscle memory. I restyle in place first, keep the order they already trust, and earn the right to change bigger things later.

Tokens are the law in our system. Colour, spacing, radius, all of it flows from a single source. But I do not treat the components as a ceiling. If the best experience needs something the system does not have yet, I build it and then fold it back in. The system serves the product, not the other way around.

The real payoff

The best moment was not any single screen. It was when the platform started to feel like one product again, made by one team with one point of view. Consistency at that scale is not a nice to have. It is something people can feel, even if they cannot name it.