Refactoring Legacy Frontend

Last updated:

Legacy systems need controlled improvement — not a rewrite that kills delivery.

01 — Purpose

Controlled improvement, not a fantasy rewrite

Legacy frontends are unavoidable — the goal is safer systems while delivery continues.

Most organisations depend on code that outlasted its original authors, frameworks, and design trends. The goal is not perfection overnight. The goal is controlled improvement without breaking the work the business still needs shipped.

See dependency management, technical debt, and JavaScript standard.

02 — Problems

What legacy usually looks like

Recognise the patterns before promising a six-month rewrite.

  • giant shared files — CSS and JS nobody wants to touch
  • duplicated logic — copy-paste features with slightly different bugs
  • inaccessible interaction — keyboard gaps, missing names, focus traps
  • inconsistent styling — three button styles, twelve greys, no tokens
  • fragile JavaScript — globals, implicit load order, no tests
  • excessive CSS specificity — overrides that only work with !important
  • abandoned dependencies — unmaintained packages still in the critical path

03 — Practice

Good refactoring practice

Reduce risk incrementally — isolate changes and measure regressions.

  • improve gradually — one route, one component, one partial at a time
  • isolate changes — feature flags, parallel CSS layers, strangler patterns
  • reduce duplication — extract modules and tokens before restyling everything
  • introduce standards slowly — naming, layers, formatting — see code formatting and style
  • measure regressions — visual checks, accessibility passes, performance budgets

Progressive improvement often means

  • extracting reusable modules — see JS module architecture
  • introducing design tokens — see design tokens
  • improving semantics and forms — see HTML standard and accessible forms
  • reducing payload — smaller CSS, deferred JS, fewer third parties
  • removing technical debt safely — deprecate, migrate, delete — with dates

04 — Avoid

Refactoring failures

Big-bang rewrites usually fail delivery — and trust.

  • “rewrite everything” — new repo, same deadline, no migration plan
  • architecture replacement without delivery strategy — standards nobody has time to adopt
  • mixing multiple new systems at once — new CSS, new JS framework, new CMS in one release
  • breaking stable functionality for aesthetic refactors
  • refactoring without governance — effort collapses back into entropy in months

Teams need conventions, review standards, architecture guidance, and named ownership — see design system governance and frontend governance.

05 — Close

Delivery must continue

Successful refactoring improves systems while the product still ships.

Legacy CSS may need quarantine in a legacy layer while new work follows LSCSS — see cascade layers and utility classes vs semantic CSS when choosing the target shape.

If the rewrite kills delivery entirely, the strategy failed — even if the new codebase is beautiful.

See JavaScript cost, keyboard navigation, and CSS code review checklist.