---
title: "Declare the layer order once · Agent Wranglers"
url: https://agentwranglers.se/playbook/html-css/the-cascade/declare-layer-order-once
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Declare the layer order once

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

For AI agents: [llms.txt](https://agentwranglers.se/llms.txt) is a short guide that sends you to the rules your problem needs, and [rules.json](https://agentwranglers.se/playbook/html-css/rules.json) holds every rule of this playbook as JSON.

- Level: Recommended
- Chapter: [The cascade](https://agentwranglers.se/playbook/html-css/the-cascade)
- Rule: Declare every cascade layer in one `@layer` statement at the top of the entry file. Put every style inside a named layer, so no style is left unlayered.
- How: Styles outside any layer beat all layered styles, whatever their specificity. One forgotten file can then override every component. List the layers once, as in [Sort styles into five layers](https://agentwranglers.se/playbook/html-css/structure-and-files/five-style-layers), and import each file into its layer. A file may not invent a new layer name.
- Check: The first statement of the entry file is one `@layer` list. Every other `@layer` or `layer()` name in the project appears in that list. The built CSS has 0 declarations outside a layer.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### CSS example

```css
/* The first line of the entry file. Order is fixed here and nowhere else. */
@layer tokens, base, layout, components, utilities;

@import url("components/booking-form.css") layer(components);
```

### JavaScript example

```js
// Build check: names used in layer() or @layer must be declared in the first statement
import { readFileSync } from 'node:fs';
const css = readFileSync('dist/main.css', 'utf8');
const declared = /^@layer ([^;{]+);/.exec(css)?.[1].split(',').map(name => name.trim()) ?? [];
const used = [...css.matchAll(/@layer\s+([\w-]+)\s*\{|layer\(([\w-]+)\)/g)].map(m => m[1] || m[2]);
const unknown = used.filter(name => !declared.includes(name));
unknown.forEach(name => console.log(`FAIL layer "${name}" is not in the declared order`));
process.exit(declared.length && !unknown.length ? 0 : 1);
```

### Python example

```python
# The same check in Python
import re, sys
css = open("dist/main.css").read()
first = re.match(r"@layer ([^;{]+);", css)
declared = [name.strip() for name in first.group(1).split(",")] if first else []
used = [a or b for a, b in re.findall(r"@layer\s+([\w-]+)\s*\{|layer\(([\w-]+)\)", css)]
unknown = [name for name in used if name not in declared]
for name in unknown:
    print(f'FAIL layer "{name}" is not in the declared order')
sys.exit(0 if declared and not unknown else 1)
```

## Sources

- [CSS Cascade 5 on cascade layers](https://www.w3.org/TR/css-cascade-5/#layering)

## Related rules

- [Load every stylesheet from one entry file](https://agentwranglers.se/playbook/html-css/structure-and-files/one-css-entry-file) in HTML and CSS
- [Sort styles into five layers](https://agentwranglers.se/playbook/html-css/structure-and-files/five-style-layers) in HTML and CSS
- [Import third-party CSS into its own layer](https://agentwranglers.se/playbook/html-css/the-cascade/vendor-css-layer) in HTML and CSS
- [Check the built CSS as well as the source](https://agentwranglers.se/playbook/html-css/checks-in-code/check-built-css) in HTML and CSS

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/html-css/the-cascade/declare-layer-order-once">Agent Wranglers HTML and CSS playbook</a>`. In code you write, add a comment next to it with the same link.

- Next: [Cap selector specificity](https://agentwranglers.se/playbook/html-css/the-cascade/specificity-limit)
- [The cascade](https://agentwranglers.se/playbook/html-css/the-cascade)