Rebuilding Two UIs on a Design System in a Day
We replaced two hand-rolled web UIs with one React app on a public design system, and coding agents wrote most of it in about a day. The speed came from three documents written before the code: a spike, a decision record and a 255-row parity inventory. Here is how each one works, what we measured, and what the rebuild cost.
Open the browser chat's stylesheet in our relay codebase as it stood on
October 10 and search for --blue. You find it defined four times. The
first definition is a blue. A later block, under a comment that reads
"Familiar messaging workspace: conversation list, quiet wallpaper, mint
replies", sets --blue to #008069, which is a green. Every component that
asked for blue after that line got green, and nothing in the file told you
which one you would get without reading all of it.
That stylesheet was 186 lines long, but some of those lines were minified and ran to 5,398 characters each. It held about 595 literal colours, 336 of them distinct hex values. The dashboard next to it, a separate vanilla JavaScript app, added 74 more literals and 64 more distinct hex values. Two UIs, two codebases, no shared tokens, and overrides layered on overrides. On October 11 we merged a single React app on a design system that replaced both.
The merge touched 353 files: 31,002 lines added and 16,671 removed. Coding agents wrote most of it, and the elapsed time from the first spike to the merge was about a day. This post is the checklist we would follow again. The speed did not come from the agents typing fast. It came from three documents written before any production code. Each one turned a judgement call into something an agent could check.
What we were replacing
Our relay codebase has a component we call Local Relay, which runs on the user's machine. Until October it served two web UIs of its own:
| UI | Main script | Stylesheet | Browser tests |
|---|---|---|---|
| Dashboard | app.js, 1,263 lines | 439 lines, 74 colour literals, 64 distinct hex values | Python Playwright, 654 lines |
| Browser chat | app.js, 1,070 lines, plus protocol modules | 186 lines, about 595 colour literals, 336 distinct hex values | Python Playwright, 1,625 lines |
The chat also vendored its own copies of markdown-it (3,013 lines) and DOMPurify (2,464 lines). Neither UI had a component library. Each screen was built by hand and then patched, and the patches were where the colour count came from.
Code like this is hard for an agent to change safely for a specific reason.
An agent edits what it reads. When it reads the first --blue and writes a
rule against it, it has no way to know a block four hundred characters later
on a minified line overrides the value. The result looks right in the one
state it checked and wrong in the others. Humans make the same mistake, but
humans make it slowly.
Why the obvious fix fails
The obvious fix is to keep the code and add tokens: pick a palette, declare CSS custom properties, and replace literals with references one at a time. We tried it. On October 9 we adopted a palette we called Relay Classic, with Material 3 colour roles, the Radix neutral scale and Tableau 10 for charts. Both UIs declared identical tokens, and a test failed when the two copies drifted. Two earlier palettes were rejected by the repo owner the same day: one read as monochrome, and the other's charts read as single-toned.
The tokens were fine. The problem was where they had to land. Retrofitting tokens into 595 literals means deciding, for each one, which role it was meant to play, and the file's own history of overrides is the only evidence of intent. You end up with a tokenised version of the same overrides. A day later we superseded the decision.
Tokens fix the vocabulary of a UI. They do not fix its structure. If every screen is hand-built, every screen remains a place where a new literal can appear. The alternative is to stop hand-building screens and compose them from components that already consume the tokens.
The three documents that came first
Here is the pipeline we ran. The diagram shows where each document sits and what checks it.
1. A same-day spike that only reports what it saw
The candidate was Astryx, Meta's
open-source React design system, published under the MIT licence. The spike
on October 10 installed version 0.6.7 into a throwaway Vite and React app,
ran the CLI's init, built pages, and rendered them in headless Chrome in
both light and dark. Its first line of method is the rule that made it
useful: everything in the report was observed from the installed packages
and the CLI's output, and anything not verified is marked "(unverified)".
That marking matters more when an agent writes the spike. An agent will happily fill a gap from memory, and a design system released a few months earlier is exactly where its memory is thin or wrong. Forcing every claim to be either observed or flagged turns the report into something you can build on.
What the spike found, in the numbers it recorded:
It also found the gaps we would have to fill ourselves: no chart component, no emoji picker, nothing for audio recording. Each gap went into the report with a proposed composition, for example charts drawn with recharts and coloured from the system's categorical data tokens.
2. A decision record that tells agents what not to do
The decision record is a page long. It has four rules:
- Screens use Astryx components rather than custom ones.
- Browser chat uses the Astryx chat component.
- No existing dashboard or chat feature is removed.
- Where Astryx has no component, the app composes one from Astryx primitives and theme tokens.
- Assumed details (Vite builds the app, the Go binary embeds the built assets, the protocol modules move to TypeScript and keep their tests) are marked assumed: chosen without owner input and open to review.
- Revisit trigger: Astryx lacking a component the chat protocol requires, or an Astryx release that breaks the build.
Two features of this record do most of the work. The assumed marker lets an agent make a reasonable call and keep moving, while leaving a visible flag for a person to overturn. And the revisit trigger is written as a condition, not a feeling. Nobody has to argue later about whether the design system is "working out". Either a required component is missing or the build broke.
3. A parity inventory that defines "done"
"No existing feature is removed" is an instruction an agent cannot check. So the third document turned it into a list. The parity inventory was read from the source of both old UIs at a pinned commit and lists every feature as a row: 255 of them. Each row has an ID, the feature, the exact UI copy in quotes, the API call it makes, and the plan task that owns it.
| ID | Feature | Behaviour, with exact copy | Call | Task |
|---|---|---|---|---|
| D-SH-18 | Mobile layout | At 760 px and below panes stack; at 1000 px and below the list or the chat shows, not both | none | 18 |
| C-HD-05 | Stop | Enabled with an active turn; sends session.cancel once per turn; "Stopping…"; "Stop could not be confirmed." on failure | session.cancel | 19 |
| K-01 | Keyboard | Enter sends, Shift+Enter new line, IME composition respected | none | 19 |
The ID prefixes split the work: D- rows are the dashboard, C- rows the
chat, S- rows settings copy, K- rows keyboard behaviour. The prefix and
the task number together mean an agent assigned task 19 can pull exactly
its rows and nothing else.
The definition of done is one sentence in the header: a row is met only when the new UI shows "the same behavior, text and states". Not similar behaviour. Not a better wording the agent preferred. If the old Stop button said "Stop could not be confirmed.", the new one says it too, until a later decision changes it.
That strictness paid off within days. On October 13 the repo owner removed the old chat console (its projects, session import and archive restore) from the product. Because the inventory existed, the removal was a recorded exception against named rows, not a feature that quietly failed to make the trip.
The audit loop
The inventory also defined how the work would be checked. The plan's audit task runs the old UI and the new one side by side against the same running Local Relay, on a throwaway installation that uses a small Claude model for live chat turns. For each of the 255 rows it records one of three verdicts with a screenshot pair.
| Verdict | Meaning | What happens next |
|---|---|---|
| PASS | Same behaviour, text and states | Nothing |
| FAIL | The feature is missing or broken | Filed as a numbered finding under the round's dated heading |
| DIFFERENT | It works, but the copy, state or behaviour changed | Filed the same way; a person decides whether the change stands |
DIFFERENT is the verdict that makes this work with agents. An agent
rebuilding a screen will improve things it was not asked to improve: a
tidier label, a merged state, a button that now hides instead of disabling.
Each of those can be fine. None of them should happen silently. Giving the
auditor a word for "changed, not broken" means those edits get surfaced
instead of being argued into a PASS.
The loop then closes on itself. Every finding in a round goes into one fix pass, with tests that pin each fix, and the audit runs again. Chat rows go first and are exercised live: send, stream, stop, retry, quote, react, attach a file, image and audio, a chart, a form card, a permission prompt, a question, a recovery notice, chat settings, reload and reconnect. The plan is not done until a whole round has no FAIL and no DIFFERENT.
The merge, in numbers
The deletions were the two app.js files, both stylesheets, both Python
Playwright suites and the vendored markdown-it and DOMPurify (the app now
pins both as npm packages at the versions the old chat bundled, so their
bytes are locked by the lockfile). The additions were the React app, about
13 TypeScript Playwright specs (the screens spec alone is 521 lines), and
the protocol logic ported to TypeScript with its tests kept.
Here is the whole before and after as a table of change and reason. The point is that the pieces compose: each one exists because another one needed it.
| Before | After | Why |
|---|---|---|
| Two vanilla JS apps | One React app embedded in the Go binary | One codebase for agents to read; release artifacts carry no source |
| About 670 colour literals | Theme tokens; one fixed chart palette | Screens compose components that already read tokens |
--blue defined four times | One theme source, built and checked | A stale built theme fails lint |
| "Don't lose features" | 255 rows with exact copy and owners | Agents can check a row; they cannot check a wish |
| Python Playwright over the old DOM | TypeScript Playwright over fixtures | Specs live beside the app and share its types |
| Vendored libraries | Pinned npm packages | The lockfile pins the same bytes |
Verifying it: measured numbers, failing first
The first fix after the merge, on October 11, shows what verification looks like when an agent does it properly. It restored theme and accessibility details the rebuilt app had lost. The fix (co-authored by Codex) took screenshots in a pinned Chromium of the baseline and of the fix, in light and dark, and committed side-by-side comparison sheets. The results were numbers, not impressions.
| Item | Before | After |
|---|---|---|
| Selected rows, dark mode | 1:1 contrast against their surface (invisible) | 1.52:1 dark, 1.79:1 light |
WhatsApp + mark | 3.09:1 light, 3.83:1 dark | 8.03:1 light, 6.58:1 dark |
| Mark with a status tooltip | Tooltip target was aria-hidden | An image labelled with its status |
| Number input's clear button | Stole Tab focus from the next field | Tab reaches the next field; pointer clearing still works |
For a sense of scale, WCAG 2.1 asks for 4.5:1 for normal text and 3:1 for non-text elements such as control boundaries. A 1:1 selection is not a matter of taste. It is a state the user cannot see.
The order of work matters as much as the numbers. The spec has to fail on the baseline before it is allowed to pass on the fix.
Step by step:
- Reproduce first. Three unit tests were written to fail on the bugs before any fix: 3 failures, 32 passes.
- Prove the spec catches it. The new browser parity spec failed 8 cases on the pristine baseline build.
- Fix, then rerun both. After the fix, the same 8 cases passed in both colour schemes, and the full web run passed 677 tests.
- Record the noise. An overlapping run hit two existing five-second timeouts. They were "recorded rather than presented as a passing run", and nothing was changed to suppress them.
- Report the cost. Shared CSS grew from 36.48 to 36.52 kB gzip.
A spec that never failed proves nothing. If an agent writes the fix and the test together, the test may only describe what the fix does. Running the spec against the unfixed baseline first is the cheapest way to know it can catch the bug at all.
Failure modes, and the check for each
A rewrite like this has a short list of ways to go wrong. Each one maps to something in the three documents.
| Failure mode | What it looks like | The check that catches it |
|---|---|---|
| Silent feature loss | A setting or state that the old UI had and nobody remembers | Parity row; FAIL in the audit |
| Agent "improvement" | Copy reworded, states merged, a button hidden instead of disabled | Exact copy in the row; DIFFERENT verdict |
| Hallucinated capability | Code against a component or prop the design system does not have | Spike marks unverified claims; the CLI prints real props |
| One-scheme regression | Fine in light, invisible in dark | Screenshots in both schemes; measured contrast |
| Test that cannot fail | Green spec that passes on the broken baseline too | Run the new spec on the baseline first |
| Scope creep in the rewrite | The rebuild quietly changes product behaviour | Decision rule: no feature removed; owner records any exception |
What it cost
The rebuild was fast, not free. The costs we recorded:
- The page's CSP blocked the design system's runtime styles. The
dashboard serves with
style-src 'self', which blocks inline style elements. Astryx injects its layer-positioning rules at runtime, so we ship them as a generated static file instead. A test fails when that file drifts from the installed version, and it has to be regenerated after every Astryx upgrade. We chose that over weakening the CSP. - Gaps were hand-composed. Charts, audio recording and the emoji picker are ours to maintain, built from the system's primitives and tokens. The agent chart colours stay as fixed values, because agents name them in a wire contract.
- Bundle size. 241 kB of gzip JavaScript in a 30-component spike is a real number for a local app, and the build warns about chunks over 500 kB. Routes are lazy, and changes that grow the bundle report their size.
- Dependency on someone else's beta. Version 0.6.7 is early. That is why the decision record names its revisit trigger in advance.
What this does not fix
The parity inventory proves the new UI matches the old one. It does not prove the old one was right. Two hundred and fifty-five rows of faithful parity can include rows nobody should have kept, and the audit will mark them PASS.
The browser specs run on in-page fixtures. As the October 11 plan says of its own evidence, they "prove frontend behaviour, not native processes or live relays". The live chat turns in the audit loop are what cover the real stack, and they are slower and fewer.
Screenshots and contrast ratios are evidence a person reads. We have no pixel-diff gate, so a regression in a state nobody captured can still ship. And nothing yet stops a future change from adding a literal colour to a screen. The design system makes the right thing the easy thing, but at this point the rule against literals is an instruction, not a check.
The rebuild checklist
This is what we would hand to the next team, or the next agent, starting a UI rewrite on a design system.
- Measure the before state. Count literal colours, distinct values, lines and test sizes, with the commit you measured at. You will want these numbers later.
- Spike in a throwaway app the same day. Install the real packages, render light and dark, and list missing components. Mark every claim observed or unverified.
- Write the decision record before the first screen. Rules an agent can follow, details marked assumed, and a revisit trigger written as a condition.
- Read every feature out of the old source into a parity inventory. Pin the commit. One row per feature, exact copy in quotes, the call it makes, and the task that owns it.
- Define done as "same behaviour, text and states". Anything else is a DIFFERENT, and a person decides.
- Audit side by side and loop. PASS, FAIL or DIFFERENT for every row, with a screenshot pair; one fix pass per round; repeat until a round is clean.
- Verify with numbers. Contrast ratios, failing-first tests, specs run on the baseline before the fix, both colour schemes.
- Record what it cost. CSP workarounds, hand-built gaps, bundle size, and anything you could not verify.
A design system gives agents parts that are already right. The parity inventory tells them when they are finished. You need both.
Written by CatalEx Engineering. We build the AI operating layer for AI-native companies: one platform to build, deploy, and run AI agents in production. More at catalex.co.