Guide
Migrating Legacy CSS
Nobody wakes up and decides to build a 9,000 line stylesheet with six layers of overrides and seventeen !important declarations. It happens slowly, like mould.
Rewriting everything is rarely realistic. Good migration work is controlled, boring, and intentionally incremental.
Common legacy problems
- global styles leaking into unrelated components
- specificity wars and endless overrides
- duplicate patterns with slightly different behaviour
- framework leftovers nobody wants to touch
- deep nesting and selector archaeology
- critical behaviour hidden inside hacks
Safer migration rules
- do not start with a full rewrite
- introduce layers before rewriting components
- move new work into the new structure first
- document hacks before removing them
- refactor around real journeys, not abstract purity
- measure regressions before celebrating cleanup
How LSCSS helps
LSCSS supports gradual adoption. Legacy code can remain isolated while new components use explicit layers, semantic naming, and predictable modifiers. Progress matters more than ideological purity.
Start here
Begin with the migration guide, decision trees, and examples. Pick one painful area, improve it properly, then repeat without starting unnecessary conflict across the team.
Recommended reading
Legacy CSS is usually a history lesson written in selectors. Read it carefully before deleting it.