Cascade Layers (@layer) on an Existing Stylesheet

You do not have to rewrite an old stylesheet to stop fighting it. Put it in a layer that you place first, and every rule you write afterwards wins, whatever the selectors look like.

Step 1: find the rule that wins for the wrong reason

Say the old CSS has this:

/* legacy.css */
.btn { background: rgb(200, 0, 0); color: white; padding: 4px; }
#page .toolbar a.btn.btn-primary { background: rgb(0, 0, 200); }

Your new .btn { background: #034bff } loses to the second rule, because an ID selector is heavier than any class you can write.

Step 2: put the old file in the first layer

@layer legacy, base, components, utilities;
@import url("legacy.css") layer(legacy);

@layer components { .btn { background: rgb(3, 75, 255); } }
@layer utilities { .bg-dark { background: rgb(8, 11, 14); } }

The first line fixes the order. @import with layer(legacy) loads the file into the first layer. Your new rules live in later layers, so they beat anything in legacy.

Step 3: check the result

I loaded a page with two links: class="btn btn-primary" inside #page .toolbar, and class="btn bg-dark". Chrome 154 reported these backgrounds:

btn btn-primary   rgb(3, 75, 255)
btn bg-dark       rgb(8, 11, 14)

The first link used my components blue, not the legacy blue from the ID selector. The second used the utilities colour. I did not edit legacy.css.

What @import costs

An @import makes the browser fetch the second file only after it reads the first one. For a production build, paste the file into the main stylesheet inside the layer instead:

@layer legacy {
  /* contents of legacy.css */
}

This gives the same cascade without the extra request. A <link rel="stylesheet"> has no layer attribute in HTML, so a layer has to be assigned in CSS.

Step 4: check the !important rules

An important rule in an earlier layer beats an important rule in a later one. Search the legacy file for !important and test those elements. Those are the ones where the order flips on you.

Common mistakes

• Declaring the order after the first @layer block has already appeared. The first mention wins.
• Wrapping only the new code in a layer and leaving the old code unlayered, which reverses what you wanted.
• Expecting layers to fix inline style="" attributes. They beat layers.

Related course: HTML and CSS Advanced.