Understanding @layer Declaration Order

@layer declaration order controls cascade precedence within the CSS Cascade Fundamentals & @layer Syntax pillar — and getting the order wrong is the single most common source of unexpected overrides in large stylesheets. When a build pipeline delivers CSS in non-deterministic order, or when a third-party library injects styles after your own rules load, cascade resolution becomes unpredictable unless you pre-register your layers explicitly. This page explains the parse-time locking mechanism, walks through how to structure multi-file architectures, and covers the edge cases that trip up even experienced CSS architects.

Concept Definition and Spec Reference

The CSS Cascading and Inheritance specification defines a cascade layer as an explicitly named grouping within the author origin. When multiple rules compete for the same property on the same element, the browser resolves the winner using this ordered sequence: origin and importance → cascade layer position → specificity → order of appearance.

Layer position is established at parse time, not render time. The first @layer statement the parser encounters — whether it contains rules or is simply a name registration — permanently fixes that layer’s position in the precedence stack. Every subsequent block or @import assigned to that name accumulates rules in the same logical slot, regardless of when that CSS arrives in the network.

Minimal syntax forms:

/* Form 1: Name-only registration — locks position, defines no rules yet */
@layer reset, base, theme, components, utilities;

/* Form 2: Named block — registers and populates in one statement */
@layer base {
  body { font-family: system-ui, sans-serif; }
}

/* Form 3: @import with layer() function — assigns an external file to a layer */
@import url('vendor/normalize.css') layer(reset);

The comma-separated form (Form 1) is the canonical way to establish your full stack before any rules arrive. Without it, each @layer block you write implicitly registers a new position at the point the parser first encounters it — which means your precedence order is determined by file concatenation or network delivery order rather than architectural intent.

How the Browser Resolves Declaration Order

Understanding the resolution algorithm precisely matters when debugging unexpected overrides. Here is what the browser does, step by step:

Step 1 — Collect the layer registry. As the parser reads your CSS, it builds an ordered list of layer names. The first @layer statement containing a given name assigns it a permanent index in this list.

Step 2 — Assign each declaration to a layer slot. Every CSS declaration is tagged with its layer index, or marked as “unlayered” if it appears outside any @layer block.

Step 3 — Resolve competing declarations. When two declarations target the same property on the same element, the one in the higher-indexed layer wins — regardless of specificity. Unlayered declarations win over all layered ones.

Step 4 — Specificity breaks ties within a layer. Only when two competing declarations are in the same layer (or both unlayered) does selector specificity come into play.

/* Canonical stack: declared once, early, in the entry stylesheet */
@layer reset, base, theme, components, utilities;
/* Effect: utilities (index 4) > components (3) > theme (2) > base (1) > reset (0) */

@layer base {
  /* Low-specificity selector, but this layer loses to components and above */
  h2 { font-size: 1.5rem; color: #333; }
}

@layer components {
  /* Even a zero-specificity * selector here beats base's h2 — layer wins first */
  .card h2 { font-size: 1.25rem; }
}

/* Unlayered: always wins over both base and components, regardless of selector */
h2 { color: navy; }

Practical Usage Patterns

Pattern 1: Flat Utility Stack

The simplest and most common pattern — a flat, linearly ordered stack that covers the full design system hierarchy in a single entry file.

/* entry.css — the first stylesheet loaded on every page */

/* Pre-declare the entire stack. The order here IS the cascade order.
   Utilities win because they are declared last. */
@layer reset, base, theme, components, utilities;

/* Assign each imported partial to its layer.
   Network delivery order no longer matters — layer precedence is already fixed. */
@import url('reset.css')      layer(reset);
@import url('typography.css') layer(base);
@import url('tokens.css')     layer(theme);
@import url('button.css')     layer(components);
@import url('spacing.css')    layer(utilities);

This pattern works because the comma-separated declaration runs synchronously before any @import is fetched. Browsers process @import rules after the current stylesheet’s parse phase, so the layer manifest is always locked in first.

Pattern 2: Nested Brand Sub-layers

When a design system needs to isolate brand-specific overrides from base component styles, nested layers create a scoped precedence hierarchy without polluting the top-level stack. For deeper detail on nesting mechanics, see Nested Layers and Inheritance.

@layer reset, base, components, overrides;

@layer components {
  /* Sub-layers are ordered within their parent scope.
     'brand' wins over 'vendor' inside the components layer. */
  @layer vendor, brand;

  @layer vendor {
    /* Third-party library defaults — lowest priority within components */
    .btn { padding: 0.5rem 1rem; background: #e0e0e0; }
  }

  @layer brand {
    /* Brand overrides — wins over vendor inside components,
       but both lose to the 'overrides' top-level layer */
    .btn { background: var(--color-brand-primary); }
  }
}

@layer overrides {
  /* Theme-time overrides from the design token system — beats everything above */
  .btn { padding: var(--btn-padding, 0.5rem 1rem); }
}

The fully qualified name for the vendor sub-layer from outside components is components.vendor. Stylelint and DevTools both display this dotted path, which is useful when debugging specificity leaks.

Pattern 3: @import layer() for Third-Party Libraries

Wrapping a vendor file in layer() at import time is the safest way to integrate third-party CSS — it confines the library’s entire rule set to a single layer slot that your own code can override cleanly. This approach is central to resolving third-party CSS conflicts.

/* Define the stack first — vendor sits below your components */
@layer reset, vendor, base, components, utilities;

/* Bootstrap is assigned wholesale to the 'vendor' layer.
   Every Bootstrap rule — regardless of specificity — loses to your 'components' layer. */
@import url('https://cdn.jsdelivr.net/npm/bootstrap@5/dist/css/bootstrap.min.css')
  layer(vendor);

/* Your components override Bootstrap without !important and without
   needing higher specificity — they simply live in a later-declared layer. */
@layer components {
  .btn-primary {
    background: var(--color-brand-primary);
    border-color: var(--color-brand-primary);
  }
}

Interaction with Adjacent Features

@layer and !important — Precedence Inversion

!important does not simply “win” inside layers; it inverts the cascade order within the !important importance context. Normal declarations resolve by the declared layer sequence (later wins). !important declarations resolve in the reverse direction — the earlier-declared layer’s !important rule beats a later layer’s !important rule.

This inversion is specified behaviour, not a bug. The full mechanics, including how user-agent and author !important interact, are covered on the Role of !important in Layers page.

@layer reset, base, utilities;

@layer reset {
  /* !important in the FIRST-declared layer wins the !important contest */
  .visually-hidden { display: none !important; }
}

@layer utilities {
  /* !important in a LATER layer LOSES to reset's !important — counter-intuitive */
  .visually-hidden { display: block !important; }
}

/* Result: display: none — reset wins the !important contest because
   !important reverses layer priority order */

@layer and Unlayered Author Styles

Rules written outside any @layer block are classified as “unlayered author styles.” They always win over every layered rule, because the spec places unlayered styles above all named layers in the same origin. This is covered in detail under Default Layer Ordering Rules.

If you accidentally leave a reset rule outside a layer, it will override everything in your components and utilities layers regardless of specificity. This is the most common silent failure mode when migrating legacy stylesheets.

@layer and Specificity

Within a single layer, specificity still operates normally. But across layers, specificity is irrelevant — a zero-specificity * selector in utilities beats a :is(html body section article div p span) selector in base. This is the architectural guarantee that makes layers valuable: you can write low-specificity component selectors and still override third-party high-specificity rules by placing your layer later. For the specificity calculation details, see Calculating Selector Weight in Layers.

DevTools and Stylelint Diagnostic Workflow

Inspecting Layer Order in Chrome and Firefox DevTools

1. Open DevTools → Elements panel → Styles sub-panel.
2. Select any element. Each matching rule now shows a layer badge (e.g. layer(components)) next to the rule origin.
3. Rules that are crossed out due to layer precedence show why they lost: hover the strike-through to see “Overridden by layer utilities” (Chrome 107+, Firefox 116+).
4. Open Sources → search for @layer to confirm your manifest declaration is the first @layer statement in the processed output.

Enforcing Declaration Order with Stylelint

Install stylelint-order and add a custom no-unknown-layer rule via stylelint-scss or a project plugin. At minimum, a Stylelint config can flag @layer blocks that appear before the manifest:

{
  "plugins": ["stylelint-order"],
  "rules": {
    "order/order": [
      { "type": "atrule", "name": "layer", "parameter": "reset, base, theme, components, utilities" },
      { "type": "atrule", "name": "import" },
      { "type": "atrule", "name": "layer" }
    ]
  }
}

Console Script — Auditing Registered Layers at Runtime

// Paste in DevTools console to inspect the live layer registry
const layers = new Set();
for (const sheet of document.styleSheets) {
  try {
    for (const rule of sheet.cssRules) {
      if (rule instanceof CSSLayerStatementRule) {
        // CSSLayerStatementRule.nameList gives the comma-list names
        rule.nameList.forEach(n => layers.add(n));
      }
      if (rule instanceof CSSLayerBlockRule) {
        layers.add(rule.name);
      }
    }
  } catch (e) { /* cross-origin sheet — skip */ }
}
console.table([...layers].map((name, i) => ({ position: i, name })));

This lists every registered layer name in the order the browser encountered it — if this differs from your intended manifest, your entry file is not being processed first.

Migration Checklist

Apply these steps in order when introducing @layer declaration order into an existing stylesheet:

1. Run a specificity audit. Identify every use of !important and every selector with specificity above (0, 2, 0) — these are candidates for layer reassignment rather than brute-force overrides. See the step-by-step specificity audit guide.
2. Define your canonical layer stack. Choose names that reflect your design system’s logical groupings: reset, base, theme, components, utilities is the recommended starting point. Write them as a single comma-separated @layer declaration at the very top of your entry file.
3. Wrap existing rule groups in @layer blocks. Start with the outermost groups (reset, base), then work inward. Keep the block order consistent with your manifest — a linter will catch drift.
4. Assign third-party imports to a vendor layer. Use @import url('...') layer(vendor) so external libraries sit below your own components and never require !important to override.
5. Remove !important declarations that were only needed to win specificity battles. Layer precedence makes them redundant and they introduce !important inversion risk.
6. Add a Stylelint rule to reject @layer blocks appearing before the manifest. This guards against future contributors implicitly registering layers in the wrong order.
7. Verify in DevTools. Check the layer badges on representative elements and confirm that overrides resolve in the expected direction. Look for any crossed-out rule that should be winning.

Edge Cases and Gotchas

Re-declaration Priority Inversion

If a developer adds @layer utilities { ... } in a feature file before the manifest @layer reset, base, theme, components, utilities; has been delivered, the browser locks utilities at position 0 — the lowest priority. The manifest then sees utilities as already registered and does not move it. Everything declared after the manifest will now beat utilities, not lose to it.

Fix: Ensure your manifest is the very first CSS parsed — in a <link rel="stylesheet"> before all others, or injected via a bundler’s additionalData or globalStyles option.

Unlayered Author Styles Always Win

Any rule outside a @layer block — including inline <style> blocks on the page and rules injected by JavaScript — automatically outranks every layered rule from the same origin. This is intentional for backward compatibility (old code that predates layers should not silently break), but it means a single unlayered vendor script can override your entire design system.

Fix: Wrap all third-party injected styles in an @layer block, or use a Content Security Policy to block unauthorised <style> injection.

Duplicate Names Across @import Chains

When two imported stylesheets each contain @layer components { ... }, the browser merges them into the layer slot established by whichever declaration (or the manifest) came first. This is correct behaviour — but it means rule order within the merged layer is determined by import sequence, which your bundler controls. Treat build-tool configuration as part of your cascade architecture.

CSS-in-JS Runtime Injection

CSS-in-JS libraries (Styled Components, Emotion, Stitches) typically inject <style> tags at the end of <head> after your stylesheet parses. If these injected rules are unlayered, they win over everything in your @layer stack. The fix is to wrap CSS-in-JS output in a layer block, either via the library’s GlobalStyles API or a wrapping @layer utilities { ... } inserted before the injection point.

@import Must Precede All Rules

@import statements are only valid before any rule other than @layer and @charset. Placing an @import after a regular rule is a parse error and the import is silently ignored. This is why the manifest form (@layer reset, base, theme, components, utilities;) is safe to write before @import — it counts as a valid pre-import statement.

FAQ

Related

• How to Declare Multiple @layer Blocks Without Conflicts — step-by-step workflow for conflict-free multi-file layer manifests
• Nested Layers and Inheritance — how child layers scope precedence within a parent layer
• The Role of !important in Layers — the precedence-inversion rule that catches most engineers off guard
• Default Layer Ordering Rules — what happens when you omit the manifest and rely on implicit layer creation
• Resolving Third-Party CSS Conflicts — wrapping vendor libraries in layers to eliminate !important override chains

Up: CSS Cascade Fundamentals & @layer Syntax