Design System Refactors Without Legacy UI Drift

Frontend refactors usually fail when they try to be two things at once: a design cleanup and a product redesign. The safer path is to decide which parts are system work and which parts are product behavior, then keep those boundaries clear.

That was the May lesson from a private AI app interface pass: the app needed a cleaner design system, a better auth shell, and fewer legacy kit fragments. It did not need a brand-new product model hidden inside a visual refactor.

For production work, this is the difference between a polished custom web application and a pretty UI that slowly drifts away from the product.

Start With the Shell

The app shell is where design system drift becomes obvious. Navigation, spacing, buttons, cards, auth screens, and empty states all meet there.

If the shell has mixed radius values, mismatched shadows, old component kits, and inconsistent typography, every new feature inherits that confusion.

The first job is not to redesign every screen. It is to make the shared frame coherent:

layout rhythm
navigation structure
type scale
action buttons
form surfaces
responsive behavior
auth entry points

Once those are stable, feature screens have something reliable to attach to.

Auth Screens Deserve Product-Level Polish

Authentication is often treated as a plugin screen. That is understandable, but it creates a sharp quality drop when the rest of the app is carefully designed.

The better pattern is to style auth as part of the product shell while preserving the auth provider's contracts.

That means:

do not rewrite secure auth logic for cosmetic reasons
keep provider components where they are the safest option
wrap them in a layout that matches the product
align spacing, radii, and background treatment
verify mobile behavior early

The goal is not to hide the auth provider. The goal is to make sign-in feel like the first page of the app instead of an unrelated detour.

Remove Legacy Kits Deliberately

Legacy UI kits are dangerous because they often linger in pieces. One old card here, one unused component folder there, one alternate button style in a forgotten route.

Removing them should be boring:

identify which components are still imported
replace or delete unused kit fragments
preserve public routes
run type and build checks
visually inspect the highest-traffic screens

The key is not to delete for vibes. Delete only when the replacement path is clear.

Tokens Are Agreements

Spacing, radius, color, and typography tokens are not decoration. They are agreements across the interface.

When a team changes them casually, the app starts to feel inconsistent even if each individual component looks fine.

Useful token questions:

Does the primary button look the same in auth and app screens?
Do cards and panels share a radius language?
Are focus states visible?
Does mobile spacing compress gracefully?
Are headings sized for the surface they occupy?

If tokens answer those questions consistently, the design system is doing real work.

What We Kept Private

This post does not include:

private design handoff files
unreleased brand assets
repository paths
auth configuration
environment variables
internal screenshots
account or user data

The public lesson is about process and system boundaries, not project-specific implementation.

Review Checklist

Before merging a design system refactor, check:

Are legacy imports actually gone?
Did auth still work after layout changes?
Do mobile auth and app screens share the same spacing logic?
Are old kit files removed only when unused?
Did the build catch stale references?
Did screenshots confirm the shell still feels coherent?

That checklist keeps a visual cleanup from becoming a regression machine.

The Takeaway

A good design system refactor makes the product feel quieter, clearer, and easier to extend. It does not smuggle in unrelated behavior changes.

May's lesson was simple: clean the shell, respect the auth contracts, remove legacy kits intentionally, and let the product get better without losing its shape.