How do I retrofit a design system into a messy AI-built app?

An incremental retrofit plan that preserves behavior while replacing repeated UI decisions with a shared system.

Better Design

Direct answer

Retrofit one user flow at a time. Inventory its styles and components, then map them to roles and primitives. Verify behavior and appearance. Avoid a full rewrite that mixes cleanup with product changes.

A hand-drawn incremental retrofit from scattered interface fragments to shared tokens, reusable components, and one coherent app.

Where should the retrofit start?

Start with one flow that matters to users and already contains repeated interface decisions. Settings, onboarding, or task creation can expose enough buttons, inputs, validation, layout, and status states. That is enough to prove the system without touching the whole application.

Do not begin by restyling every page. First record the current behavior and establish a reversible checkpoint. The retrofit should make the interface easier to explain while preserving the task users can already complete.

What should you inventory?

  • Global CSS variables, theme files, literal colors, fonts, spacing values, radii, shadows, and breakpoints.
  • Buttons, inputs, dialogs, tables, navigation patterns, empty states, and feedback messages that solve the same job in different ways.
  • The routes and data flow behind the chosen user task, including loading, error, empty, and success states.
  • Tests, screenshots, accessibility checks, and analytics that describe the current behavior.
  • The smallest change that can introduce a shared token or component without forcing unrelated pages to move at once.

How does the incremental retrofit work?

The incremental retrofit path

Five checkpoints replace repeated decisions without turning the migration into a rewrite.

A hand-drawn path from interface inventory through one flow, semantic tokens, shared components, and verification.
  1. Inventory: Record repeated styles, components, states, and current behavior.
  2. Choose one flow: Select a bounded user task with enough repeated UI to prove the system.
  3. Map tokens: Replace repeated values with named semantic roles before changing the look.
  4. Consolidate components: Move the chosen flow onto approved shared primitives and variants.
  5. Verify and repeat: Confirm behavior, accessibility, responsiveness, and visual consistency before the next flow.

What does this look like in Better Design?

For a messy settings area, the agent can use Better Design's extraction tool to read the existing CSS. The tool derives a semantic starting palette. The agent can then load form and hierarchy guidance, reuse or install shadcn-compatible source, and review the finished flow.

A first slice might replace three different save buttons and two input treatments in the profile form with approved variants. The agent preserves profile loading, validation, error, and success behavior. The team checks the diff before moving to notification settings.

Retrofit only the profile settings flow. Inventory its tokens, input and button variants, validation, loading, error, and success states. Map repeated values to the existing semantic roles. Reuse approved components and keep data behavior unchanged. Verify keyboard use, 320px layout, tests, and the rendered states before proposing the next flow.

What should stay out of the first pass?

  • New product features, data-model changes, authentication work, and dependency upgrades unrelated to the chosen flow.
  • A wholesale visual redesign before the current patterns and user behavior are understood.
  • Renaming every token or component when a compatibility layer can keep the migration reversible.
  • Deleting old primitives before repository search proves that no remaining surface depends on them.
  • Claims of improved usability or conversion without a defined test and evidence.

How do you know the retrofit worked?

  • The chosen task still passes its valid, invalid, loading, empty, error, and success checks.
  • The flow uses fewer literal styling values and fewer duplicate primitives than before.
  • Keyboard use, focus, labels, contrast, and narrow layouts pass the agreed checks.
  • A reviewer can trace the interface back to named tokens and shared components.
  • The next flow can reuse the system without copying page-specific exceptions.

Questions

Should I rewrite an AI-built app before adding a design system?

Usually not. Preserve working behavior, establish a checkpoint, and migrate one bounded flow. A rewrite mixes product risk with system cleanup and makes regressions harder to isolate.

Which flow should I retrofit first?

Choose a high-value, frequently changed flow with several repeated UI decisions and reliable behavior checks. Avoid the most security-sensitive or migration-heavy area for the first slice.

When can I delete the old components?

Delete them only after repository search and tests show that no remaining surface depends on them. Keep the change reversible until the migrated flow passes its acceptance checks.

Implementation references

Primary documentation used for the product workflow, registry, token, and accessibility practices on this page.

Related

Start the Better Design retrofit