CSS cascade layers explained

Where layers sit in the cascade

When two declarations target the same property on the same element, the browser walks a fixed resolution order. Importance (!important) still tops everything, but for normal declarations the order is roughly:

1. Origin and context (author vs user vs browser)
2. Layer order — later-declared layers beat earlier ones
3. Specificity of the selector
4. Source order (later rules win ties)

That means a low-specificity rule in a higher layer beats a high-specificity rule in a lower layer. This is the opposite of how CSS worked for decades, where a single ID selector could bulldoze hundreds of class rules regardless of architecture. Layers give you intentional override lanes instead of specificity inflation.

Declaring and assigning layers

Establish layer order once at the top of your entry stylesheet:

@layer reset, tokens, vendors, components, utilities;

Then wrap rule blocks:

@layer components {
  .card { padding: var(--space-4); border-radius: var(--radius-md); }
}

@layer utilities {
  .u-hidden { display: none !important; }
}

You can also use blockless assignment: @layer components; followed later by @layer components { ... }, or nest imports: @import "vendor.css" layer(vendors);

Unlayered styles, nesting, and @import

Unlayered declarations win all layered rules

Any rule not inside a layer participates in an implicit final layer that beats every named layer, regardless of specificity. That is powerful for one-off fixes but dangerous if accidental: a stray unlayered rule in button.css can override your entire utility layer. Lint for unlayered blocks in design-system repos and document exceptions.

Nested layers

Layers can nest: @layer framework { @layer layout, theme; } creates framework.layout and framework.theme. Order is scoped inside the parent. Useful when wrapping a meta-framework (e.g. importing a component library as a subtree you can reorder relative to your tokens).

@import layer() and preload

Prefer bundler concatenation in production, but native layered imports help prototypes:

@import url("normalize.css") layer(reset);
@import url("datepicker.css") layer(vendors);
@import url("./components.css") layer(components);

Layer order is fixed when the first @layer name appears; import statements that assign layers must respect that declaration. Combine with preload hints when vendor CSS is render-critical.

A practical layer stack for design systems

A stack that works for content sites and dashboards:

• reset — box-sizing, margin zeroing, accessible focus defaults. Lowest layer; never fights anything above.
• tokens — custom properties for color, spacing, typography. No element selectors that collide with components.
• vendors — third-party widgets, chart libraries, legacy Bootstrap fragments. Sandboxed so their class names cannot escape.
• components — cards, nav, forms. Moderate specificity; BEM-style single classes are fine because layer order protects utilities.
• utilities — layout helpers, spacing atoms, display toggles. Wins over components without !important in most cases.

Frameworks mirror this: Tailwind emits @layer base, components, utilities in its preflight pipeline; Tailwind v4 users extend the same stack in src/input.css. Plain CSS projects gain the same structure without a build step beyond concatenation.

Layers do not replace container queries or subgrid — they organize who wins conflicts, not how layout behaves.

Harbor Commerce vendor-CSS refactor (worked example)

Problem. Checkout loaded 47 KB of vendor CSS (date picker, payment iframe skin) globally. Harbor's component layer used 0,1,0 and 0,2,0 selectors; vendor rules mixed 0,2,0 and 0,3,0. QA logged 23 visual regressions per release tied to specificity duels and six instances of !important on focus rings.

Change. Rebuilt checkout.css entry:

@layer reset, tokens, vendors, components, utilities;

@import "./reset.css" layer(reset);
@import "./tokens.css" layer(tokens);
@import "vendor/datepicker.css" layer(vendors);
@import "vendor/payment-skin.css" layer(vendors);
@import "./checkout-components.css" layer(components);
@import "./checkout-utilities.css" layer(utilities);

Moved all Harbor rules into named layers; left payment iframe overrides as documented unlayered exceptions (three rules, code-reviewed). Replaced !important focus fixes with utilities-layer classes.

Results. Visual regression suite failures dropped from 23 to 2 per sprint (both legitimate vendor upgrades). Median checkout CSS specificity score fell from 0,2,1 to 0,1,0 in components. Lighthouse unused-CSS audit unchanged, but developer time on override bugs fell an estimated 4 h per sprint in team retro notes.

Lesson. Layers excel when third-party CSS is immovable. If you control all sources, consistent naming (BEM, utilities) may suffice — layers add value at integration boundaries.

Technique decision table

Common pitfalls

• Accidental unlayered rules — one orphan file overrides the entire utility layer; enforce layer wrappers in CI or stylelint.
• Declaring layer order too late — first assigned layer locks order; put @layer a, b, c; at the very top.
• Expecting layers to fix load order alone — async stylesheets still race; layers resolve conflicts after all sheets parse.
• Mixing layered and !important — important layered rules beat unlayered normal rules; document any important utilities explicitly.
• Over-layering atomic utilities — ten nested layer names add cognitive cost; five top-level layers cover most products.
• Ignoring @layer in older WebViews — unsupported browsers ignore layer at-rules and fall back to classic cascade; test embedded WebViews if you ship hybrid apps.

Production checklist

• Declare full layer order in the first stylesheet the page loads.
• Assign every project-authored rule block to a named layer.
• Import third-party CSS into a dedicated vendors layer via @import ... layer().
• Audit for unlayered rules quarterly; justify each exception in code review.
• Keep component selectors at low specificity (single classes) now that layers handle overrides.
• Mirror layer names in documentation and Storybook READMEs for contributors.
• Pair with lint rules (stylelint-layer-names) to block new unlayered files.
• Regression-test checkout and auth flows after vendor CSS upgrades.
• Verify focus-visible and :has() states after removing !important hacks.
• Document layer stack in DESIGN.md or equivalent for design-engineering handoff.

Key takeaways

• @layer adds a cascade step before specificity — later layers beat earlier ones regardless of selector weight.
• Unlayered styles beat all named layers; accidental unlayered rules are the main footgun.
• Vendor CSS belongs in a low layer; tokens, components, and utilities stack above it.
• Tailwind and other frameworks already map to layer semantics — align custom CSS with the same stack.
• Layers solve integration-boundary conflicts; they do not replace layout features or scoping strategies in SPAs.

Related reading

• CSS fundamentals explained — selectors, specificity, and classic cascade rules
• Tailwind CSS fundamentals explained — base, components, and utilities layers in practice
• CSS :has() selector explained — parent-conditional rules that layers should not break
• Responsive web design explained — breakpoints and layout without specificity wars