Skip to main content

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.

CatalEx Engineering · Published October 14, 2026 · 09:00 UTC

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:

UIMain scriptStylesheetBrowser tests
Dashboardapp.js, 1,263 lines439 lines, 74 colour literals, 64 distinct hex valuesPython Playwright, 654 lines
Browser chatapp.js, 1,070 lines, plus protocol modules186 lines, about 595 colour literals, 336 distinct hex valuesPython 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:

168components, including a full chat set
0chart components (data-viz tokens only)
241 kBgzip JS for an app using about 30 components

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:

docs/decisions/2026-10-10-dashboard-react-astryx.md
  • 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.

dashboard/docs/specs/2026-10-10-dashboard-feature-parity.md (three rows)
IDFeatureBehaviour, with exact copyCallTask
D-SH-18Mobile layoutAt 760 px and below panes stack; at 1000 px and below the list or the chat shows, not bothnone18
C-HD-05StopEnabled with an active turn; sends session.cancel once per turn; "Stopping…"; "Stop could not be confirmed." on failuresession.cancel19
K-01KeyboardEnter sends, Shift+Enter new line, IME composition respectednone19

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.

VerdictMeaningWhat happens next
PASSSame behaviour, text and statesNothing
FAILThe feature is missing or brokenFiled as a numbered finding under the round's dated heading
DIFFERENTIt works, but the copy, state or behaviour changedFiled 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​

353files in the merge commit
+31,002lines added
−16,671lines removed
255parity rows to meet

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.

BeforeAfterWhy
Two vanilla JS appsOne React app embedded in the Go binaryOne codebase for agents to read; release artifacts carry no source
About 670 colour literalsTheme tokens; one fixed chart paletteScreens compose components that already read tokens
--blue defined four timesOne theme source, built and checkedA stale built theme fails lint
"Don't lose features"255 rows with exact copy and ownersAgents can check a row; they cannot check a wish
Python Playwright over the old DOMTypeScript Playwright over fixturesSpecs live beside the app and share its types
Vendored librariesPinned npm packagesThe 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.

ItemBeforeAfter
Selected rows, dark mode1:1 contrast against their surface (invisible)1.52:1 dark, 1.79:1 light
WhatsApp + mark3.09:1 light, 3.83:1 dark8.03:1 light, 6.58:1 dark
Mark with a status tooltipTooltip target was aria-hiddenAn image labelled with its status
Number input's clear buttonStole Tab focus from the next fieldTab 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:

  1. Reproduce first. Three unit tests were written to fail on the bugs before any fix: 3 failures, 32 passes.
  2. Prove the spec catches it. The new browser parity spec failed 8 cases on the pristine baseline build.
  3. Fix, then rerun both. After the fix, the same 8 cases passed in both colour schemes, and the full web run passed 677 tests.
  4. 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.
  5. 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 modeWhat it looks likeThe check that catches it
Silent feature lossA setting or state that the old UI had and nobody remembersParity row; FAIL in the audit
Agent "improvement"Copy reworded, states merged, a button hidden instead of disabledExact copy in the row; DIFFERENT verdict
Hallucinated capabilityCode against a component or prop the design system does not haveSpike marks unverified claims; the CLI prints real props
One-scheme regressionFine in light, invisible in darkScreenshots in both schemes; measured contrast
Test that cannot failGreen spec that passes on the broken baseline tooRun the new spec on the baseline first
Scope creep in the rewriteThe rebuild quietly changes product behaviourDecision 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.

  1. 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.
  2. 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.
  3. Write the decision record before the first screen. Rules an agent can follow, details marked assumed, and a revisit trigger written as a condition.
  4. 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.
  5. Define done as "same behaviour, text and states". Anything else is a DIFFERENT, and a person decides.
  6. 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.
  7. Verify with numbers. Contrast ratios, failing-first tests, specs run on the baseline before the fix, both colour schemes.
  8. 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.