Aero StudioWhat we got wrong shipping a design system
A few years ago we delivered a design system we were proud of. Sixty components, a coherent token set, thorough documentation, the lot. Four months later, adoption across the client's four product teams was close to zero.
The library was good. That turned out to be almost irrelevant.
We built it in isolation
We worked from an audit of the existing interfaces, consolidated the variations, and designed what the system should be. It was a clean solution to the problem as we understood it, produced without involving the engineers who would have to adopt it.
When we handed it over, every team had the same reaction: this is nice, and migrating to it is three sprints we do not have. There was no moment at which adopting the system was easier than not adopting it, and so nobody did.
A design system is not a deliverable. It is a migration, and migrations need a plan that someone has agreed to.
We optimised for completeness over the first step
Sixty components is intimidating. Nobody adopts sixty components. They adopt a button, and then a form field, and then they notice the modal is easier to use than the one they have.
What we should have shipped first was the six components that appeared most often across all four codebases, in a form that could drop into existing code without a refactor. Boring, incomplete, immediately useful.
We wrote documentation for the wrong reader
Our documentation explained the system: principles, token structure, the reasoning behind the spacing scale. All accurate, all written for someone evaluating the system as a whole.
The actual reader is an engineer with a ticket open, who needs to know whether this component does the thing they need and what props it takes. They arrive from a search, read one page, and leave. Nothing about our documentation was designed for that visit.
Nobody owned it
We finished the project and left. The system had no maintainer, so the first time a team needed a variation that did not exist, they built it locally — correctly, given their deadline. Within a few months the fragmentation we had been hired to fix was quietly regrowing, now with an unused library sitting alongside it.
What we do differently
- Engineers in the room from week one. Not a review at the end. The people who will adopt it help decide what it is.
- Ship the smallest useful set first — usually five or six components — and get them into production before designing anything else.
- Migration path per component. If we cannot describe how an existing screen moves to it in under an hour, it is not ready.
- Documentation written for someone in a hurry. What it is, when to use it, when not to, props, one example you can paste. Principles go somewhere else.
- Name an owner before we finish. If the client cannot name one, we say so plainly, because the system will decay without it and that is worth knowing before the budget is spent.
We ran the same engagement again eighteen months later with a different client and these constraints in place. Twelve components at handover instead of sixty, and all twelve in production before we left.