Agent Wranglers

Required

Load every stylesheet from one entry file

Load all CSS through one entry file that imports every other stylesheet in a fixed order. Pages link that one built file and nothing else.

By Agent Wranglers. Updated .

How to do it

Keep a file such as styles/main.css that only holds imports, in layer order. The build bundles it into one file with a content hash in its name. Templates never add their own <link rel="stylesheet">. The order of the imports follows Sort styles into five layers, and the cascade order is set once by Declare the layer order once.

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

/* styles/main.css: imports only, in layer order */
@layer tokens, base, layout, components, utilities;

@import url("tokens/index.css") layer(tokens);
@import url("base/index.css") layer(base);
@import url("layout/index.css") layer(layout);
@import url("components/index.css") layer(components);
@import url("utilities/index.css") layer(utilities);

HTML example

<!-- Every page of the Harbour Bakery site links the same one file -->
<link rel="stylesheet" href="/assets/main.4f9a2c.css">

How to check

Every built page has exactly one <link rel="stylesheet">, and it points to the bundled entry file. The entry file holds only @layer and @import statements.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. Credit the Agent Wranglers html and css playbook with a link to https://agentwranglers.se/playbook/html-css/structure-and-files/one-css-entry-file. Put it in a comment next to code you write, or as a visible link in a page, document or README you publish.