# CSS @layer in Practice: Cascade Layers Instead of Specificity Wars
> Cascade layers from the ground up: syntax, cascade order, frameworks like Bootstrap and Tailwind in their own layer, shadow DOM and design tokens.
Source: https://www.jpkc.com/db/en/blog/css-cascade-layers/
There is one line of CSS almost everyone has written and regretted afterwards:
```css
.sidebar .widget ul li a.link { color: #fff !important; }
```
That line is not styling. It is a surrender. Someone wanted to change a colour, lost to a selector, prepended another class name, lost again, and finally reached for `!important`. The result works — until somebody else plays the same game one level up.
Since March 2022 there has been a proper answer to this in every browser engine: **cascade layers**, the `@layer` at-rule. At-rules are CSS statements starting with an `@` — `@media`, `@import`, `@supports`; they either end in a semicolon or wrap a block of their own. This one adds a step to the CSS cascade that sits *above* specificity. (The cascade is the algorithm a browser runs to pick a winner among competing values for the same property — it is not inheritance.) Instead of inflating selectors, you state once in which order your style tiers apply — and from then on the later tier wins, no matter how weak its selector is.
This article is the long tour: the rules (each one measured in a real browser rather than copied from documentation), migrating a website that actually grew over years, frameworks like Bootstrap and Tailwind in their own layers, the relationship with web components and shadow DOM — and a pattern that lets design tokens carry their own layer assignment.
> **A note on method:** every behavioural claim in this article was checked against a real browser (Chromium engine, Edge 151, headless, `getComputedStyle`). Where documentation and specification disagreed, the measured result is what you read here — that actually happened once, further down.
## The problem: specificity is a poor ordering system
Before `@layer` existed, you had exactly three levers to decide which of two competing declarations wins. A **declaration** here means exactly one `property: value;` pair; a **rule** is the selector plus the braced block holding one or more declarations. The three levers:
1. **Origin and importance** — browser stylesheet, user stylesheet, author stylesheet, plus `!important`.
2. **Specificity** — the familiar count of ID, class and element selectors. The browser counts three slots per selector: IDs — classes, attributes and pseudo-classes — elements and pseudo-elements. `#hint` comes to 1-0-0, `.box.box.box` to 0-3-0, `div.box` to 0-1-1. They are compared left to right; the higher value wins.
3. **Source order** — on a tie, the last declaration wins.
All three are perfectly adequate for small stylesheets and unfit for large projects. The reason is structural: **specificity is a property of the selector, not of the intent.** What you want to say is "this rule belongs to my design system and components may override it". What you are able to say is "this rule has two classes and one element". Those are entirely different statements, and CSS forces you to use the second one to mean the first.
Hence the well-known trajectory of every larger project:
- First selectors get longer, in order to win.
- Then `!important` appears, because selectors no longer suffice.
- Then `!important` appears in the other direction, because the first one is in the way.
- In the end nobody dares delete anything.
Methodologies like BEM (Block Element Modifier), SMACSS (Scalable and Modular Architecture for CSS) or ITCSS (Inverted Triangle CSS) are all attempts to solve this with **discipline** — through conventions for naming and file order: keep specificity flat, order the file so that generic things come first and important ones sit at the bottom. That works as long as everyone plays along — and breaks the moment third-party CSS enters, which by its nature does not follow your convention.
Cascade layers solve the problem at the right place: they make **intent** a first-class part of the cascade.
## What cascade layers actually are
A cascade layer is a named bucket for CSS rules. You define the order of the buckets once, and from then on:
> **Among competing normal declarations, the bucket declared later wins — regardless of the specificity of the selectors inside it.**
That is the entire core idea. Everything else is detail and edge cases.
The minimal example:
```css
@layer base, components;
@layer base {
#notice { color: red; } /* specificity 1-0-0 */
}
@layer components {
.notice { color: green; } /* specificity 0-1-0 */
}
```
The element renders **green**. The ID selector loses to a class selector because `components` was declared after `base`. In classic CSS that was simply impossible.
### The cascade in full
To use `@layer` safely you need to know *where exactly* layers sit in the cascade. The specification ([CSS Cascading and Inheritance Level 5](https://www.w3.org/TR/css-cascade-5/)) sorts competing declarations in this order — the first criterion that makes a difference decides:
1. **Origin and importance** (browser / user / author, each normal and `!important`)
2. **Encapsulation context** (shadow DOM tree — a whole chapter on that below)
3. **Element-attached styles** (the `style` attribute)
4. **Layers**
5. **Specificity**
6. **Order of appearance**
Two things about this matter in practice and are frequently missed:
**Layers rank above specificity, but below inline styles.** A `style="color: red"` in the HTML beats every layer. `@layer` therefore does not replace the rule "no inline styles in markup".
**The encapsulation context ranks above layers.** This is why `@layer` and shadow DOM behave differently than most people first assume — the chapter on that comes later.
And here is the complete ranking in the author part of the cascade, from weakest to strongest — the two animation ranks are strictly their own origins reaching into it:
| Rank | What |
|---|---|
| 1 (weakest) | First layer, normal |
| 2 | Second layer, normal |
| … | further layers, normal |
| 3 | **Unlayered** rules, normal |
| 4 | Inline styles, normal |
| 5 | Running CSS animations |
| 6 | **Unlayered** rules, `!important` |
| … | further layers, `!important` — **in reverse** |
| 7 | Second layer, `!important` |
| 8 | First layer, `!important` |
| 9 | Inline styles, `!important` |
| 10 (strongest) | Running CSS transitions |
The two rows that cause bugs are rank 3 and rank 6 — more on both shortly.
## The syntax: five forms, that is all
### 1. The order declaration
```css
@layer reset, base, components, utilities;
```
This line creates four empty layers in exactly that order. It belongs at the very top of your stylesheet — it is the contract the rest of the file fulfils. Where the rules physically live afterwards no longer matters.
That is the single most useful trick of the whole at-rule: **order is fixed by the first mention of a layer name, not by the position of the rules.** So you can keep sorting your file the way humans read it.
### 2. The layer block
```css
@layer components {
.btn {
border-radius: 0.4rem;
padding: 0.5em 1em;
}
}
```
You may open the same layer as often as you like. The browser merges all blocks of the same name into one layer; inside the layer, specificity and source order apply again as usual.
```css
@layer components { .btn { padding: 0.5em 1em; } }
@layer utilities { .p-0 { padding: 0; } }
@layer components { .card { padding: 1rem; } } /* still sorts before utilities */
```
That is not sloppiness but the intended way to work with files that already exist — it is exactly how the jpkc.com migration described below was done.
### 3. Anonymous layers
```css
@layer {
/* rules without a layer name */
}
```
A block without a name creates a layer nobody can reference, extend or reorder afterwards. Every additional `@layer { }` creates a *new* anonymous layer. Useful for code you deliberately want to seal off; unsuitable for anything you still need to touch.
### 4. Importing into a layer
```css
@import url("bootstrap.css") layer(framework);
@import url("legacy.css") layer; /* anonymous layer */
```
Note the second line: for an anonymous layer the keyword stands **without parentheses**. `layer()` with empty parentheses looks plausible but is not a valid value — and the error handling is what makes it nasty: the whole `@import` becomes invalid, the stylesheet does **not load at all**, and no console error appears. Measured: the imported rules are simply gone.
This is how you get a foreign stylesheet into a layer without touching its contents. It is the core of the framework chapter below.
One thing about document order: `@import` must come before all other rules — **with exactly two exceptions**, `@charset` and `@layer` **statements**. That means the statement form `@layer a, b;` only. A `@layer name { … }` **block** placed before it invalidates every following `@import`; the specification notes explicitly that layer blocks cannot be interleaved with `@import` rules. So the following is valid, and it is the recommended way to write it:
```css
@layer framework, app; /* pin the order first */
@import url("bootstrap.css") layer(framework); /* then import */
```
### 5. Nested layers
```css
@layer components {
@layer card { /* … */ }
@layer button { /* … */ }
}
/* equivalent, using dot notation: */
@layer components.card { /* … */ }
@layer components.button { /* … */ }
```
Nested layers create a sub-ranking inside their parent. The name is bound to the parent: `components.card` and `utilities.card` are two entirely different layers.
The point is namespacing. A framework can use `framework.reset`, `framework.base`, `framework.components` internally without those names colliding with your own `reset`/`base`/`components`.
## Eight rules you need to know
The following eight points are what actually causes surprises in practice. Each one comes with the measured result from a real browser.
### Rule 1: layers beat specificity — always
```css
@layer a, b;
@layer b { #box { color: blue; } } /* 1-0-0 */
@layer a { .box.box.box { color: red; } } /* 0-3-0 */
```
**Measured: blue.** Inside a layer, specificity still counts exactly as before. Between layers it counts for nothing at all.
This is the property you adopt `@layer` for: in a later layer, a single class selector can override something the earlier layer set with an ID selector.
### Rule 2: order is fixed at first mention
```css
@layer a { #box { color: red; } }
@layer b { #box { color: green; } }
@layer b, a; /* too late */
```
**Measured: green.** The two blocks already created the layers in the order `a, b`. The trailing declaration line changes nothing — it merely mentions two layers that already exist.
The practical consequence: **an `@layer` order line only has an effect if it precedes every affected block.** So it belongs on the first line of your entry stylesheet — and in exactly one file, not several.
### Rule 3: unlayered styles beat every layer
```css
@layer everything { #box { color: blue; } } /* 1-0-0, layered */
div.box { color: green; } /* 0-1-1, unlayered */
```
**Measured: green.** Unlayered rules behave as if they lived in an implicit final layer — and the final layer wins.
That is both very handy and very dangerous:
- **Handy**, because in an existing codebase you can start pulling parts into layers without the still-unlayered remainder suddenly becoming weaker. Migration without a big bang.
- **Dangerous**, because every file you *forget* to layer automatically gets top priority. A single forgotten `` to a third-party stylesheet defeats your entire layer architecture. More on that below.
### Rule 4: `!important` reverses the order
This is the rule that causes the most confusion, and it is entirely consistent by design: in CSS, `!important` has always meant "invert the normal balance of power" — which is why user `!important` rules beat author ones. Layers follow the same principle.
```css
@layer a, b;
@layer a { #box { color: red !important; } }
@layer b { #box { color: blue !important; } }
```
**Measured: red.** With `!important`, the **earlier** layer wins.
And the follow-on:
```css
@layer whatever { #box { color: blue !important; } }
#box { color: red !important; } /* unlayered */
```
**Measured: blue.** Unlayered `!important` rules are the **weakest** of all author `!important` rules — the mirror image of rule 3.
Remember: a layer placed early is the weakest for normal declarations — and the strongest for `!important`. That double role is the lever behind the Bootstrap recipe below.
### Rule 5: nested layers behave like their parent in miniature
```css
@layer c.card { #box { color: red; } }
@layer c.button { #box { color: green; } }
```
**Measured: green.** Inside `c` the same logic applies: declared later wins.
And the edge case worth seeing once:
```css
@layer c;
@layer c.child { #box { color: red; } }
@layer c { #box { color: green; } } /* directly in c, not in a child */
```
**Measured: green.** Rules that sit *directly* in the parent count as an implicit final sub-layer — so they beat every named child. With `!important` this reverses too (then the first child wins).
### Rule 6: `revert-layer` hands control back to the previous tier
```css
@layer base, theme;
@layer base { .btn { color: green; } }
@layer theme { .btn { color: red; }
.btn.plain { color: revert-layer; } }
```
**Measured: green** for `.btn.plain`. The value is not reset to its initial value (that would be `unset` or `initial`) but to whatever the *previous* tier would have set.
Two edge cases, both measured:
- **`revert-layer` in the lowest layer** falls all the way through to the browser stylesheet. An `` with `color: revert-layer` in the only layer resolved to `rgb(0, 0, 238)` — the browser's default link blue.
- **`revert-layer` in unlayered CSS** falls back to the tier below — that is, the last explicit layer that **actually sets** the property, not the browser stylesheet. Tested with two layers `l1` (red) and `l2` (green) plus an unlayered `color: revert-layer` — result: **green**, the value from `l2`. If `l2` does not set the property, it falls through to `l1`; if no layer sets it, you do end up at the browser stylesheet after all.
The second point is notable because widely circulated summaries claim otherwise (namely a blanket fallback to the browser stylesheet). The measured behaviour matches the specification: unlayered CSS *is* the implicit final layer, so "previous layer" is the last named one. Nor is it a Chromium quirk — the Web Platform Tests cover exactly this case (`css/css-cascade/revert-layer-002.html`), and it passes in Chrome, Firefox and Safari.
And a limit: `revert-layer` is a normal declaration. It cannot beat an `!important` from another layer — measured as well.
### Rule 7: a layer that was only declared still holds its slot
```css
@layer first, second;
@layer second { #box { color: green; } }
@layer first { #box { color: red; } }
```
**Measured: green.** The declaration line created both layers; the fact that `second` is filled first in the text is irrelevant.
One detail for the advanced: layers created *inside* a `@media` condition only come into existence when the condition matches. Your layer order then depends on the viewport. That is rarely intended — always declare the order outside any conditional block.
### Rule 8: animations and transitions outrank everything
```css
@layer everything { #box { color: red; } }
#box { animation: shift 100s step-end forwards; }
@keyframes shift { from { color: green; } to { color: green; } }
```
**Measured: green.** A running animation beats every normal declaration, layered or not; a running transition beats even `!important`. That is not layer-specific, but it explains a share of the cases where `@layer` appears "not to work".
## Practice 1: migrating a site that grew
The case I can document best is the main site, [jpkc.com](https://www.jpkc.com/en/). Its CSS grew over years, carries a Bootstrap 4 legacy in the reset, and is written **as a single file inlined into every page** (around 1,900 lines, minified with `lightningcss`). A textbook candidate: lots of existing code, no appetite for a rewrite.
The migration was a single commit and consisted of exactly two moves.
**First**, pin the order, right after the custom properties:
```css
@layer reset, base, components, utilities, responsive;
```
**Second**, wrap the existing sections in blocks — without moving a single rule:
| Layer | What went in |
|---|---|
| `reset` | `html`, `body`, `:target`, scrollbars, the `:focus-visible` baseline |
| `base` | typography, links, code, media, tables, forms, `::selection` |
| `components` | buttons, dropdown, SVG icons, header, main area, navigation, ``, footer |
| `utilities` | `.visually-hidden`, spacer, `.box`, directory-tree list, light toggle |
| `responsive` | all `@media` blocks — breakpoints, `inverted-colors`, print |
The file kept its section order. Because multiple blocks of the same name merge (see the layer block rule), `@layer components { … }` appears at several points in the file — that is intended, not a mistake.
Three decisions from it generalise:
**Tokens stay unlayered.** The `:root` block with all custom properties sits *before* the layer declaration and outside every layer. (Custom properties are CSS variables: declared as `--name: value`, read with `var(--name)`; they inherit to descendants. `:root` is the pseudo-class matching the document's root element, in HTML the `` tag.) That gives design tokens unconditional priority so no component can accidentally override them. Whether that is the right call depends on the project — the design tokens chapter below argues the opposite position.
**`responsive` as its own layer is the real win.** Previously: a `@media` block overrode a component rule only if it appeared later in the source *and* had at least equal specificity. Both had to be kept in mind while editing. Now the media block always wins because its layer is last — even with a simpler selector. That had been failure mode number one when touching old breakpoints.
**The `!important` reversal was deliberately recorded.** In the new order, the `!important` in `.visually-hidden` (layer `utilities`) is *stronger* than any `!important` in the print stylesheet (layer `responsive`). There is currently no collision because the two set different properties — but exactly this kind of constellation needs a pass and a note during migration. If you carry a lot of `!important`, inventory it before you start.
**And the cost?** Exactly +83 bytes per page after minification — the same 83 bytes on every page, because it is simply the at-rule lines. For a file inlined into every HTML document in full, that works out to between 0.06 % (home page) and 0.18 % (shortest subpage), depending on page length. For external stylesheets, compression makes the effect smaller still. `@layer` costs practically nothing.
One note on trusting your toolchain: `lightningcss` **preserves** layer semantics when minifying; it does not strip the at-rules. A minifier rewrites CSS for minimum size — merging adjacent rules, folding longhand into shorthand — and `lightningcss` is one such tool, written in Rust. That is not a given and should be verified once against the output of whatever build tool you use — a minifier that "optimises away" `@layer` blocks inverts your entire cascade.
### The migration recipe in short
1. Declare the `@layer` order at the very top.
2. Wrap existing sections *in place*; move nothing.
3. Place custom properties deliberately (inside or outside — but decide).
4. List every `!important` in the project and re-check the reversal.
5. Build, then check the minified output for surviving `@layer` blocks.
6. Diff visually. If the order is chosen correctly, nothing changes — which is precisely the goal.
## Practice 2: putting Bootstrap in its own layer
The real headline use case for `@layer` is third-party CSS. Take Bootstrap as the example, because it is the most widespread and because its behaviour is nicely measurable.
I downloaded the current distribution and counted — Bootstrap 5.3.8, `dist/css/bootstrap.css`, around 280 KB:
- **`@layer` occurrences: 0.** Bootstrap 5 ships no cascade layers. Everything lands unlayered — and by rule 3 that puts it *above* everything you put into layers.
- **`!important` occurrences: 1,716.** The lion's share comes from the utility API — a Sass generator that turns a configuration map into classes like `.m-1` or `.text-danger`. A **utility class** has exactly one purpose and is combined with others in the markup; `.mt-0` sets `margin-top: 0`, `.text-center` centres the text. Every generated utility class carries `!important` by default so it reliably overrides its component.
Those two numbers describe the problem precisely. Anyone customising Bootstrap is not fighting its specificity but its position in the cascade, and 1,716 `!important` declarations.
### Step 1: the framework into an early layer
```css
@layer framework, app;
@import url("bootstrap.css") layer(framework);
@layer app {
.btn {
border-radius: 0; /* wins — no !important, no selector inflation */
}
}
```
**Measured: works.** A single class in `app` beats Bootstrap's component rules regardless of how they are built. The whole toolbox of "prepend another class" and "`.btn.btn.btn`" becomes unnecessary.
This is the point where working with a framework changes qualitatively: you no longer need to know its selectors in order to override them. You only need to know that your layer comes later.
### Step 2: the `!important` trap
Now the catch most tutorials leave out. By rule 4 the layer order reverses for `!important`. Bootstrap sits in `framework`, the *earliest* layer. Therefore:
**In this arrangement, Bootstrap's 1,716 `!important` declarations are stronger than your own `!important` declarations in `app`.**
Tested with Bootstrap's `.text-danger { color: … !important }` against an `!important` in the later `app` layer: **Bootstrap wins.** That is not a bug but the logical consequence of rule 4 — and it reliably surprises everyone meeting it for the first time.
### Step 3: the override layer
The fix is a layer that sits **before** the framework and exists purely for `!important` counterfire:
```css
@layer bs-overrides, bootstrap, app;
@import url("bootstrap.css") layer(bootstrap);
@layer bs-overrides {
/* Only !important rules meant to defeat Bootstrap utilities. */
.text-danger { color: var(--brand-danger) !important; }
}
@layer app {
/* Everything normal — beats Bootstrap without !important. */
.btn { background: var(--brand); }
}
```
**Measured: both work.** `bs-overrides` wins the `!important` duel (earlier layer), `app` wins the normal duel (later layer). One layer per direction.
It looks like a trick at first, but it is defensible: you have two different intents — "I want to extend the normal case" and "I want to defeat a framework's emergency brake" — and in a cascade with a reversal, two intents need two slots.
**The better fix if you compile Bootstrap yourself:** simply turn off `!important` on the utilities. Bootstrap has a Sass variable for it — Sass being a CSS preprocessor with its own language (`$name` variables, mixins, nesting) that a build step compiles to CSS; SCSS is its CSS-like syntax:
```scss
$enable-important-utilities: false;
@import "bootstrap/scss/bootstrap";
```
Without `!important` on the utilities the entire second layer problem disappears and plain layer order suffices. The variable has existed since Bootstrap 5.0 and sits in `scss/_variables.scss` as `true !default`.
### The Sass pitfall
Anyone pulling Bootstrap in through Sass hits a real tooling limit: **`@use` may not appear inside a block in Sass.** (`@use` loads a Sass file as a module whose variables, mixins and functions are namespaced; `@forward` passes them on. Both replace the deprecated `@import`.) So this is not valid Sass:
```scss
@layer bootstrap {
@use "bootstrap/scss/bootstrap"; /* error: @use must be at the top level */
}
```
A `layer()` argument for `@use` and `@forward` was proposed in 2022 but rejected within days — with the note that Sass already has a tool for this. And that tool is the clean route:
**`meta.load-css()` loads a Sass module right where you are** — including inside a `@layer` block:
```scss
@use "sass:meta";
@layer bootstrap {
@include meta.load-css("bootstrap/scss/bootstrap");
}
```
Tested with Dart Sass 1.102.0: this compiles to `@layer bootstrap { … }` with the full framework CSS inside — and no deprecation warning. The difference from `@use` matters: `meta.load-css()` only emits the **CSS**; it does **not** give you the module's variables, mixins and functions. Those you still load at the top via `@use` — and that division of labour is exactly the point.
That leaves three workable routes, in this order:
1. **`meta.load-css()` inside the layer.** The official route, no expiry date, no extra file. First choice when the framework runs through your Sass pipeline anyway.
2. **Compile the framework separately.** Build Bootstrap into its own `.css` file and pull it in via `@import url(…) layer(bootstrap)` from a slim CSS entry point. Cleanest separation, independent of Sass — sensible when you do not customise the framework at all.
3. **Wrap after the build.** A PostCSS step puts the entire compiled framework output into a layer. Robust and toolchain-agnostic, at the cost of an extra build step.
The formerly common nested `@import` inside `@layer { }` still works but raises a deprecation warning — `@import` will be removed in Dart Sass 3.0. Do not use it in new code.
### The `` pitfall
And now the mistake that silently makes an entire layer architecture worthless.
**A `` cannot be assigned to a layer today.** There is no `layer` attribute for ``. The corresponding proposal has been with the CSS Working Group for years but is implemented in no browser.
By rule 3 the consequence is harsh:
```html
```
```css
/* third-party.css */
#box { color: red; } /* specificity 0-1-0-0 */
```
**Measured: red.** The weaker rule from the linked stylesheet wins because it is unlayered. Your carefully built layer order is powerless against it.
The workaround is an intermediate stylesheet: a tiny CSS file that does nothing but import the real files into layers.
```css
/* main.css — the only file loaded via */
@layer reset, framework, base, components, utilities;
@import url("reset.css") layer(reset);
@import url("bootstrap.css") layer(framework);
@import url("base.css") layer(base);
@import url("components.css") layer(components);
@import url("utilities.css") layer(utilities);
```
But you have traded in a performance problem: `@import` chains resolve **serially**. The browser must fully load and parse `main.css` before it even learns that it needs `bootstrap.css` — and CSS blocks rendering, meaning nothing is painted until it has loaded and parsed (otherwise unstyled HTML would flash up). With five imports you are waiting on at least two full round trips — one round trip being a complete request-and-response to the server and back.
The workable answer for production: **bundle at build time.** Your bundler (esbuild, Vite, Lightning CSS, PostCSS — the last of these not a preprocessor with its own language like Sass, but a tool that rewrites CSS at build time through JavaScript plugins) resolves the `@import` statements and writes the `@layer` blocks straight into one file. You keep the clean source structure, the browser gets a single request. If you do leave `@import` in place at runtime, at least kick off the affected files with ``.
## Practice 3: Tailwind CSS v4 — the layers are already there
Anyone on Tailwind version 4 is already working with real cascade layers, whether they want to or not. Tailwind v3 had an `@layer` construct that only *looked* like the CSS at-rule: it was a PostCSS directive, evaluated and removed at build time. Version 4 uses native layers and writes them into the output.
This can be shown straight from the build of the site you are reading. The head of the generated `main.css` (Tailwind 4.3.0):
```css
/*! tailwindcss v4.3.0 | MIT License | https://tailwindcss.com */
@layer properties { … }
@layer theme { … }
@layer base { … }
@layer components { … }
@layer utilities { … }
```
Five layers in that order. The first of them is conditional: `properties` only appears when the generated utilities actually need registered custom properties — a minimal build without such classes emits just `theme, base, components, utilities`. What that means for your own code:
**Your own unlayered CSS beats every Tailwind utility.** That follows from rule 3 and is the most common cause of "my utility class has no effect". If you load a custom component file via `@import` alongside Tailwind and it sits in no layer, it beats `@layer utilities` — and therefore `p-4`, `text-center` and everything else.
The fix is to place your own CSS as well:
```css
@import "tailwindcss";
/* Sort custom components below the utilities so utility classes
in the markup keep the last word. */
@layer components {
.prose-card {
border-radius: 0.75rem;
padding: 1.5rem;
}
}
```
**New utilities have their own route.** Tailwind v4 ships the `@utility` directive, which registers a class as a genuine utility — you write it straight into your CSS file (`@utility tab-4 { tab-size: 4; }`). That brings variant support (the `hover:` and `md:` prefixes that bind a utility to a state or a breakpoint) and correct placement into the `utilities` layer. A hand-written `@layer utilities { … }` does not get any of that.
**And a framework above the framework?** If you combine Tailwind with another third-party stylesheet, you can move the entire Tailwind output into a parent layer by layering the import:
```css
@layer vendor, tw, app;
@import "tailwindcss" layer(tw);
```
Tailwind's own layers then become `tw.theme`, `tw.base`, `tw.components` and `tw.utilities` — the internal order is preserved, and the block slots in as a whole between `vendor` and `app`. That is the nested namespacing from the syntax chapter in its most useful form.
**There is one exception**, measured against a real build: `properties` escapes the nesting. The layer stays at the top level and is declared even before `vendor` — making it the weakest in the entire document. Harmless, since it only supplies starting values, but it means only four of the five layers move into the namespace.
Which also settles what `properties` actually does: it holds a `@supports` block that emulates registered custom properties where the browser does not know them yet. The condition targets two engines at once — older Safari **and** older Firefox versions (before 128).
## Practice 4: third-party widgets, embeds and legacy code
The third classic use case is everything you neither control nor want to touch: embedded booking widgets, consent banners, chat windows, the CSS of an old section nobody understands any more.
The reflex here is the **anonymous layer** — and it makes a surprisingly easy trap visible. This example does **not** do what it promises:
```css
@layer app; /* ❌ app is now the FIRST layer */
@import url("widget.css") layer; /* ❌ the anonymous layer is created AFTER it */
```
Measured: the widget wins. The explanation is rule 2 — order is fixed at first mention. `@layer app;` mentions `app` first and thereby makes it the weakest layer; the import's anonymous layer is created afterwards and is consequently stronger. Anonymous layers have exactly this quirk: because they carry no name, you cannot pull them forward in **any** order line. Their position follows solely from where the import sits.
The right move is therefore a **named** vendor layer placed at the front of the order line:
```css
@layer widget, app; /* foreign code first = weakest layer */
@import url("widget.css") layer(widget);
@layer app {
/* your code — wins every normal contest */
}
```
**Measured: works.** You put the foreign code into a layer that sits at the front, and never have to mention it again. Nobody accidentally extends it, and your own CSS wins every normal contest.
If the layer really must stay anonymous, the import has to come **before** everything of your own — the order is then right, but you give up the ability to document it explicitly later. In practice the named layer is almost always the better choice.
For in-house legacy code a named layer is better:
```css
@layer legacy, modern;
@layer legacy {
/* The old section, pasted in unchanged. */
}
```
The effect is a technical debt haircut: everything in `legacy` automatically loses against everything new. You can leave old code lying rather than defusing it — and pull it out piece by piece without priorities shifting in between.
## Web components: what layers can do — and what they cannot
A word on vocabulary first: **web components** is the umbrella term for your own HTML elements with encapsulated internals. A **custom element** is such a self-defined element (hyphenated name, registered via `customElements.define()`); attached to it is a **shadow DOM** — a separate, sealed-off DOM tree whose styles are scoped and which ordinary document selectors do not reach into.
This is where it gets interesting, because the common expectation is wrong. Anyone who understood `@layer` as "a priority system for CSS" assumes it can also govern the boundary between page and web component. It cannot — and for a very clear reason.
### The encapsulation context ranks above layers
Recall the sort order from the second chapter: **encapsulation context** is criterion 2, **layers** only criterion 4. Encapsulation context simply means which tree the declaration comes from — document or shadow tree. So the browser first checks which tree a declaration came from, and only reaches the layer question if both came from the same tree.
The rule for the encapsulation context reads:
> For **competing** declarations on the same element, **normal** declarations from the **outer** tree win, and **`!important`** declarations from the **inner** tree win.
The word "competing" carries weight here. The rule only applies where two declarations actually fight over the same element — that is, via `:host`, `::part()` and `::slotted()`. Everywhere the document cannot select the elements inside the shadow tree at all, the component wins anyway, and an inherited value loses to any shadow rule.
Measured on a custom element with an open shadow root:
```html
…
```
```js
shadow.innerHTML = ``;
```
**Measured: green.** The document rule wins — even though the shadow rule sits in the later layer of its tree. The layer was never consulted.
And the counter-test with `!important`:
```html
```
```js
shadow.innerHTML = ``;
```
**Measured: blue.** Now the inner tree wins.
### Layer names do not cross the shadow boundary
The second key point: **every shadow tree has its own, entirely independent layer order.** A `@layer components` in the document and a `@layer components` in a shadow root are two different things that know nothing about each other.
Measured: if the document declares `@layer b, a;` while the shadow tree mentions `a` first and `b` second without an order line of its own, the inner first-mention is what counts — the document's order line has no effect whatsoever.
That is consistent with the purpose of shadow DOM: encapsulation is precisely the promise that outer structure means nothing inside. Two refinements belong here though, because the short version "layers and shadow DOM have nothing to do with each other" is too coarse in both directions.
**First: a global `@layer reset` does partly reach shadow trees.** Anything selector-bound stays outside — a `* { box-sizing: border-box }` from the document has no effect inside the shadow tree. **Inheritable** properties, however, flow in exactly as they always did: a `font-family: monospace` and a `letter-spacing: 3px` from the document reset were measurably in effect inside the shadow tree. Since a real reset consists of both, its typography half arrives in full.
**Second: a layer API to the outside is possible — but through the tree, not across the document boundary.** As long as your CSS lives in the document, you cannot slide a layer under the component; the encapsulation context decides first. If your stylesheet ends up *inside* the shadow tree, however — because the component accepts and adopts a `CSSStyleSheet`, or because its shadow root is open and you append a `