Skip to content
← Work log

Sending the design system back for a rebuild

With the tokens in, the plan was to port the components one at a time, starting with the small ones everything else builds on. The first was a 35-line status mark, and porting it properly (with a check that renders the design system's own preview next to ours and compares them pixel by pixel) is what made the real problem obvious. Every one of the design system's components was written with inline styles in JavaScript, hover states tracked in JavaScript too, every size in pixels, and React 18 loaded from a global script. That's a perfectly sensible way to build things that only ever have to live inside a Claude artifact. It's just not how the actual site is built.

Claude counted it up: about 2,600 style declarations across 87 components, all needing to be rewritten as CSS rather than just converted, plus a few hundred hard-coded pixel values I'd want as rem. Doing that here, one component at a time, would have meant 87 slightly different rewrites with nothing upstream to check them against. So instead we wrote one long prompt describing the state I actually wanted the design system in, and I handed it to Claude Design, which built the system in the first place.

The prompt asked for React 19, every component moved onto CSS Modules with the same cascade layers the site uses, every size in rem, nothing that would break when the pages are rendered on the server, and the tooling and docs updated to match. The rule was zero visual change, and it had to prove it. It took a baseline of 350 screenshots before touching anything (every preview at rest, hovered and focused, in both themes), then worked through the components in thirteen batches over the evening, comparing every pixel after each one and checking everything again with the browser text size turned up. Along the way it found seven components that would have crashed on the server, all because of one shared hook reading the browser during render, plus an old bug where the inline styles had been quietly turning one loader's tiles the wrong colour. It wrote the whole thing up at the end, including everything it wanted to change but didn't.

The 35-line status mark I'd ported earlier now has to be redone against the new version, which is a small price. The bigger lesson is for next time. The design system was built first and wired up to the site second, so it was built to suit its own previews rather than the codebase it was always going to live in. If I make another one in Claude Design, the first thing I'd give it is the target: the framework and version (React 19 with TypeScript), how the CSS is written (native CSS in CSS Modules, cascade layers, rem, tokens as custom properties), and that pages are prerendered on the server. That's a paragraph at the start that would have saved a whole evening at the end.

rebuild
AI-OMETER— DISCLOSURE INDEX
MACHINE-LED80%