CSS Cascade Layers: Control Your Cascade

Why it exists

CSS specificity can be hard to manage in large projects. Developers often resort to complex selectors or !important to force a style to apply. Cascade Layers were created to provide an explicit, top-level way to organize CSS and control which group of styles wins, sidestepping specificity battles.

The mental model

Think of Cascade Layers as labeled buckets for your CSS rules: a reset bucket, a framework bucket, a components bucket, and a utilities bucket. You define the stacking order of these buckets. A rule in a later bucket (e.g., utilities) will always override a rule in an earlier bucket (e.g., components), even if the component rule has a more specific selector. Layer order beats selector specificity.

How it works

You declare the order of layers with @layer reset, base, components, utilities;. The last layer listed, utilities, has the highest priority for normal styles. You can then add styles to these layers anywhere in your code using @layer components { ... }. A key rule is that any style not in a layer automatically overrides any normal style that is in a layer. However, the reverse is true for !important rules: an !important rule inside a layer beats an !important rule outside a layer. For !important rules, the layer priority is also inverted: the first declared layer wins.

When to use it

Use layers to structure the CSS architecture of a large application or design system. It's perfect for integrating third-party styles (like a reset or framework) and ensuring your own theme styles or utility classes can reliably override them. For example, you can place a third-party library in a framework layer and be confident your components layer styles will apply over it.

When not to use it

For very small projects with a single stylesheet, layers might be overkill. They add a level of abstraction that isn't necessary if you aren't facing specificity conflicts. Be cautious when mixing layered and unlayered styles in a legacy codebase, as the unlayered styles will have unexpectedly high precedence for normal rules.

One canonical example

Imagine a generic button style in a component layer and a utility class for adding a red background. First, define the order: @layer components, utilities;. Then, define the styles: @layer components { .btn { background-color: blue; } } and @layer utilities { .bg-red { background-color: red; } }. A button with <button class="btn bg-red"> will be red. The .bg-red rule from the utilities layer wins over the .btn rule from the components layer, because the utilities layer was declared last.