In this article
In April a client asked us to move more than 700 pages of their corporate website onto a new design system. Every page was hand-written HTML, built up over years by many different developers. The new design came as a Storybook of components, plus a spreadsheet that mapped each old CSS class to its new component.
Our first tool for the job lasted five days. This post is about why we threw it away, what we built instead, and how much of the first idea came back anyway. The results are in the case study. This is how we got there.
Attempt one: a tool for any website
We started with html-migrator, a command-line tool. The goal was something we could reuse on any site: drop in the old pages, the Storybook and the mapping spreadsheet, then run one command.
AI did the setup. It read the spreadsheet, worked out which columns mattered, matched old classes to Storybook components, and suggested rules for classes the spreadsheet didn't cover. A person approved or rejected each suggested rule. Then a plain script did the rewrite, with no AI involved.
It was tidy. It had 70 tests that ran without spending a single AI token, and not one site-specific name in the code. It just didn't fit the pages we actually had.
Why it didn't work
A script only does what its rules say, and a rule says "this old class becomes that component". The old site didn't use its classes consistently. The same box might have an extra wrapper on one page, a different tag on another, an inline style on a third, or no class at all. Some blocks were three old components stacked into one.
A script can't tell that two blocks are the same thing written differently. Anything it couldn't match stayed untouched and went on a list for a person to fix. On this site, that list was going to be most of the work.
So we started again.
Attempt two: let AI read every page
The second version, built with Claude Code, flipped the split. Instead of AI writing rules for a script, AI reads every page. We wrote it as a set of Claude Code skills and four agents, each with one job:
- The analyst reads the old HTML and explains what each block is and what it's for. It never decides what the block should become.
- The architect maps each block to a new component and says how confident it is. If nothing fits, it says so instead of guessing.
- The transformer rewrites the page and keeps every piece of content.
- The critic compares old and new and hunts for anything lost: a dropped caption, missing text, placeholder text leaking in from a template.
We also gave the agents a third answer besides "migrated" and "skipped": manual. When a block was too unusual to convert safely, they left the old markup in place and flagged it, instead of producing something that looked right and wasn't.
Then half the first idea came back
A week in, we spotted waste. A heading with an obvious one-to-one mapping still went through all four agents. That's four AI passes to change a heading.
So we added a rules engine: plain rules, written down in files, for classes with an obvious mapping. It started with headings only, because those were safe. Any class without a tested rule still went to the agents, or to manual. Within days, rules covered 102 of the 119 old classes we were tracking.
In other words, we rebuilt the part of the first tool that worked. The difference was where it sat. The script handled the mechanical cases, and AI handled everything that needed judgement.
Making it cheap enough for 700 pages
By late April, about ten real migration runs had cost $17. That's fine for a test, not for 700 pages. Three things were adding up:
- Every run used Opus, our most expensive model.
- Every file started a fresh session and reloaded the same context.
- The architect read the full 384 KB component map, when a 16 KB summary was enough for 97 of the 119 classes.
We made Sonnet the default, ran files in batches so shared context loaded once, and pointed the architect at the summary first. We estimated that would cut the cost of a run by about 70%.
Two weeks, 700 pages
In June the design team delivered a finished version of the mapping spreadsheet, with the exact new markup for every old component. We made it the main source of truth and changed the flow to work one page at a time: plan the whole page, have a person check the plan, then rewrite it, review it and open a pull request.
Then the team ran it. Between 9 and 20 June we merged more than 700 migration pull requests, 254 of them on a single day. Each came with a preview link, so a reviewer could see the page in the new design before merging it.
What we'd tell ourselves in April
- Don't build the general tool first. We built for any website before we understood this one. The reusable parts showed up anyway, once the real pages forced them.
- Use scripts for what you can write down, and AI for what needs judgement. The first tool was all script. The first version of the second was all AI. The one that worked was both.
- Give the AI a way to say "I don't know". The manual level and the confidence ratings did more for quality than any prompt change.
- Watch the bill early. $17 for ten runs is nothing. At 700 pages, it's a design problem.
Next in this series: how people who don't write code ran the migration themselves, from a GitHub issue form.
Planning a migration of your own? Read the case study, or tell us about your site.
All articles
