Migrating a legacy product to a new design system

• Rebuilt the library on shadcn/ui with semantic tokens, structured variables, and documented usage rules

We had a design system already. On paper, that should have meant faster, more consistent product work. In practice, developers were routing around it. New screens were being built from scratch instead of assembled from the library, and the inconsistency the system was supposed to prevent was creeping back in anyway.

The easy conclusion would have been that the developers were not disciplined enough. I did not believe that, so I went to find out why a system built to help was being avoided.

I sat with the developers and traced how they actually worked. The root cause was not attitude, it was the system itself. The components were over-constrained: so rigid and so locked down that bending one to fit a real requirement took more effort than rebuilding it from scratch. The library was optimizing for control at the expense of the people using it, so they rationally opted out.

That reframed the problem entirely. This was not an adoption problem to be solved with mandates or documentation. It was an architecture problem. The system had to be rebuilt to be flexible enough that using it was genuinely faster than not using it.

I framed the initiative around a single idea: design should be an enabler, not a blocker. A design system only earns its place if it makes building faster. I positioned the rebuild not as a maintenance chore but as a product North Star, something the whole product organization moves toward because it compounds across every future screen.

The manager responsible for the transition was resistant. Rather than let the work stall there, I took the case, and the evidence from the developers, past that manager to the technology directors, and secured the direction and the room to rebuild properly.

I rebuilt the library on shadcn/ui, chosen because it gives a flexible, composable base instead of a rigid black box. The new system is built on semantic tokens and structured variables, so a value like a color or spacing unit has one meaning and one source of truth, and it flexes across contexts without forcing a rebuild. I documented clear usage rules so the system is legible to the people consuming it, and crafted components with Claude Code to move quickly without sacrificing quality.

The goal throughout was concrete and practical: make the fastest path to a good screen the one that goes through the system.

The instinct in a low-adoption situation is to push harder on the people not adopting. The more useful move was to assume they were behaving rationally and find out what the system was costing them. Once the problem was architecture rather than attitude, the fix was clear, and reframing the rebuild as an enabler is what let me escalate past a stuck manager to the directors and actually get it done. Design earns trust when it makes building easier, not when it enforces rules.