The design system has been happening in parallel, and not in this repo at all. It lives in a Claude artifact (one of the Design System pages you can make on claude.ai), and over the last few days it grew into something fairly serious — 93 components, a dark and a light theme, its own lint rules and checks, and a "lab" where new ideas get tried out before they're allowed in. It's built on the HUD look I'd been playing with for LANDCU.BE (the topographic map project), so one system now covers both. The display type got picked this morning from a shortlist of twenty — Barlow Condensed for the big moments, Zilla Slab as the accent, and Geist for everything else.
When I came back to the rebuild and asked Claude where we'd left the design system, it went digging through git history, stashes and old worktrees and came back with "we haven't started". Which was fair from where it was standing, because none of it was in the repo. Once I pointed it at the artifact it found the handover doc we'd been keeping in there, which still had wiring conor.fyi up to the system sitting at low priority on the list, "deferred until the system is hardened".
So the first step was just getting a copy into the repo as a reference. 564 files went into src/design-system, exactly as they are in the artifact. The fonts were the awkward bit — they're stored as separate uploads rather than files, so they had to be pulled down one at a time and renamed from their IDs, and each one got checked against the checksum the artifact records for it. Nothing imports it yet, it's just sitting there so Claude and I can read it without going back to the artifact every time.
Then the React version. The site is on React 19 and the design system was on 18, and I'd assumed the upgrade would mean going through all the components. It didn't — they only use hooks and the basic stuff, nothing React 19 got rid of. The actual problem was how React gets loaded. The whole system reads React from a global window.React, which used to come from React's ready-made browser scripts, and React 19 doesn't ship those anymore. So Claude wrote a small script that builds our own copies with esbuild (8KB for React, 180KB for ReactDOM) and pointed everything at them. The type definitions needed a tweak as well, because React 19's types dropped the global JSX namespace — Claude missed one of those on the first pass, and the strict type check caught it.
Before touching anything, Claude ran the system's own checks against the untouched copy to get a clean baseline, then ran them again after the upgrade. Every component preview renders in both themes on React 19, and the compiled bundle came out byte-identical, which is a nice way of proving the components themselves didn't change. Getting the two demo apps to load in a headless browser took a second go, because the browser wouldn't fetch their source files from the local disk, but that was the test setup rather than the upgrade.
I made a call to do the upgrade on the copy in the repo only, so the artifact is still on React 18 and the two have drifted apart. It's noted in the repo and it's an easy sync whenever I want to do it, but it's the kind of thing that's very easy to forget about.
Next up is the bigger question — whether the site loads the design system's bundle as it is, or whether the components get ported over to TypeScript properly.