Miraee: Design System Redesign

A design system is supposed to be the one place every screen comes from: build a component once, reuse it everywhere, change it in one place. Going AI-first was supposed to make that faster.

Instead, rapid AI-assisted development exposed a flaw in our first system. The generators kept losing context and hallucinating UI. They are biased towards the cheapest path: regenerate a component rather than reuse one, copy whatever code is nearest, build only what is on screen. So every feature we shipped faster made the system worse, not better, across web, iOS and Android.

I audited all three codebases to see exactly how AI generation was failing the product.

Read alongside industry research (DORA, GitClear), the audit resolved into three patterns in how a generator works — and four things that follow from them.

1. 01

   The economics of reuse flipped

   Generating a screen takes three hours. Building a shared component takes three hours. Reuse no longer pays back inside a sprint, so it loses every time.
2. 02

   Verification debt

   96% of developers do not fully trust AI code, but fewer than half review it. It looks beautifully formatted, so reviewers skim and miss the duplication.
3. 03

   The isEmpty rule

   Every page had loading and error states, because isLoading already existed in the code. Only 5% had empty states, because isEmpty did not. The system survives only where the code hands you the decision.
4. 04

   It lands on design

   Engineering is measured on speed; QA passes it because it renders. Design is left holding the drift months later, when it is obvious.

Where this is heading

The share of UI that is generated rather than drawn or hand-written is only going up. McKinsey's estimate of raw developer productivity by level of support makes the slope plain:

Raw productivity potential by level of developer support, multiple. Source: McKinsey & Company.

People and models both take the cheapest path. Five moves put the right thing on it:

1. 01

   Notes for the AI, at the top of the codebase

   A short Markdown file at the repo root: which components exist, which to reach for when, which states are mandatory. Plus a per-page note listing the components that page uses. The generator reads the system before it writes.
2. 02

   A website the AI can scrape, instead of Figma

   The reference site became the source of truth: 117 pages published as plain Markdown with an index at the root — 55 documenting what ships today across all three platforms, 62 specifying what replaces it. A Figma library assumes a human comes to look. Markdown in the repo is what the generator actually reads.
3. 03

   Reduce what there is to process

   One typeface. Fewer, higher-coverage components — one card with variants covering all four radii, not two cards and two hand-rolls. Tokens renamed into language a model can guess: status-success, not sage-400. Closed scales for spacing, radius and type, so there is no open range to interpolate into.
4. 04

   Turn methodology into checklists

   Markdown files developers and AI both follow: states required, tokens only, volume-tested at 500 rows before done. Procedure lives in files, not memory — so it survives deadlines, handoffs and generation speed.
5. 05

   Make the right thing arrive on its own

   Generalise the loading-state result: the data layer returns an emptiness signal the way it already returns isLoading, so an empty state becomes a variable you would have to deliberately ignore. Delete the 39 dead components — dead code copies exactly as well as live code. Seed every platform with something correct to copy: Android stayed the cleanest app with zero library, because it had iOS to copy line for line.

And measure rather than assert: the audit is a repeatable script, re-run at milestones, which is what turned adoption from a claim into a number.

Considered and rejected

The test for the whole strategy: can a generator pull the right component faster than writing a new one?

A design system serves several audiences, and they pull against each other. Optimising for a designer browsing a library produces a different system from optimising for a generator retrieving a component. The order below is a decision, and it came from how UI was actually being produced at Miraee.

One designer covered three platforms. Engineers closed the gaps themselves, largely with AI generation. So most UI entering the product was neither drawn by a designer nor hand-written by an engineer — it was generated. The system's highest-volume consumer was a machine. Designing first for a human browsing a library would have meant optimising for the smallest user.

Accessibility sits underneath all four as a gate, not a lens: nothing ships that fails it. And the ordering deliberately deprioritises per-screen visual tailoring, designer-authored one-offs, and a Figma-first workflow where design leads and code follows. With one designer and three platforms, code is where the system has to live, and its artefacts have to be readable by whatever is generating the code.

A generator — or a rushed developer — only reliably follows a limited amount of documentation at once. The more rules and variants it has to hold, the more it silently skips. So the fix was not "make things consistent"; it was to reduce how much the system needed to remember in order to stay consistent. Fewer typefaces, fewer components, fewer rules. That is the direct reason for collapsing to one typeface, and for building variants of one card instead of maintaining several near-identical ones.

Measured with the same audit script that produced the audit findings, re-run at milestones against the same baseline.

• One typeface, one accent colour, one grey scale. Every colour must pass contrast before it is added.
• Every component must define loading, empty and error states before it ships.
• One rule for what opens where: inline, popover, panel, sheet, dialog, new page.
• Written for a machine to parse: short rules, no exceptions buried in prose.
• Adoption is tracked, so it cannot silently drift again.

• Track adoption from day one, not after the fact.
• Test with real data volumes earlier — most lists were designed against six sample items.
• Decide how the system stays maintained before designing it. Manual token syncing is what caused the drift the first time.