Migrating legacy CSS without breaking things

The "wrap and replace" pattern

You inherit a 5000-line legacy stylesheet. You want to migrate to @layer + tokens. You CAN'T rewrite it all at once.

Strategy:

@layer legacy, modern;

@layer legacy {
  /* Wrap the entire 5000-line legacy file */
  @import url("/legacy.css") layer(legacy);
}

@layer modern {
  /* New code goes here. ALWAYS wins over legacy. */
  .new-card { ... }
}

The legacy layer is at the BOTTOM of priority. Any modern rule beats it without needing !important or higher specificity.

Replace incrementally

1. Build a new component in modern layer.
2. Apply it to a single page.
3. Verify visual parity.
4. Apply to the next page.
5. Eventually delete the legacy rules for that component.

Months later: legacy layer is empty. Delete the import.

Don't fight the cascade

If a legacy rule applies an unwanted style to your modern component, DON'T add !important or stack 7 classes. Just put it in the modern layer:

@layer modern {
  .new-card { color: blue; }   /* Beats any legacy color */
}

When this doesn't work

• If legacy uses !important AND you can't edit it. !important cuts ACROSS layers. You'd need a HIGHER-priority !important.
• If legacy uses inline styles. Inline beats EVERYTHING except !important on a normal rule.

In both cases, edit the source if you can. If you can't, you're stuck doing CSS-fu the old way.