Before porting anything, I had Claude do a planning pass where it asks every question it can't answer from the code before committing to anything. That turned up the big one straight away — every one of the design system's 74 components is styled with inline styles, with hover states tracked in JavaScript. That's fine inside an artifact, but it's not how I want the actual site built, so moving to proper modern CSS means rewriting the styling of every component rather than just converting it.
The decisions that came out of it: plain native CSS with no runtime, CSS Modules for the components when they arrive, everything in cascade layers, and Lightning CSS (which Vite already ships with) compiling it for browsers from roughly the last two years. So things like light-dark(), oklch() colours, relative colours, nesting and :has() are all fair game, and anything newer than that only goes in as an extra. The other big call was that the site now wins — the code in the repo is the design system from here on, and the artifact becomes a sketchbook for trying ideas. That one was forced a bit, because the artifact's token format can't hold the newer CSS anyway.
The fonts went to a Sonnet agent in its own copy of the repo while Claude did the tokens, which worked well. It subset everything down to just the weights the type scales actually use and self-hosted them as woff2, so a normal post page now loads about 54KB of fonts instead of pulling them from Google. It also generated fallback fonts sized to match each real font, so the page shouldn't jump much when the real ones arrive. There's a small Python script in there for working out those sizes, which is the one non-TypeScript file in the project. I'm fine with that.
The tokens got ported by hand, but with a check. Every colour was converted to oklch and then converted back to make sure it landed on exactly the same colour as the original hex, and all of them did. Light and dark are now one set of tokens rather than two, using light-dark(), so the theme just follows the OS. There's a toggle in the nav as well, with a tiny script at the top of the page that applies your choice before anything gets drawn. The pages are prerendered, so without that you'd get a flash of the wrong theme on every load.
A few things went sideways along the way:
- A route file starting with an underscore is a layout in TanStack, not a URL, so the hidden
/_systemspecimen page has to be called[_]system.tsx. Then it got prerendered anyway, even though nothing links to it, because TanStack prerenders every static route. - Vite's CSS minifier has its own browser target that defaults to something more conservative than ours, and it would have quietly rewritten the new syntax into older fallbacks. Claude checked the built CSS to confirm the modern stuff survived.
- The screenshots caught the specimen page's colour swatches running off the edge, and the hidden radio buttons in the theme toggle sitting in odd places.
Then I asked Claude to run the whole thing and check it was working. It did a sweep of every page in both themes, and everything rendered with the right colours and fonts and no errors. It also found that a few posts with wide tables overflow on a phone, and went straight into building a component to make tables scroll. I stopped it there. We're not building components yet, and it's meant to look broken at this stage.
That led to the bigger correction. I'd assumed base.css (the styles for plain HTML elements) had come straight from the design system. It hadn't — Claude had written most of it itself (a reading column, heading sizes, list markers, a styled nav) and described it as "adapted from" the system, which undersold it. I want the system's own rules, so base.css is now exactly what the design system has, with one change: a light-theme link colour rewritten so it also works when the light theme comes from the OS. The reset file Claude had added went too.
So right now the site is the design system's fonts and colours on top of browser-default layout, and it looks fairly broken, which is the point. Nothing on this branch ships until everything's been ported. Next up is the components themselves.