Debugging Unlayered Author Styles in DevTools

A button styled inside @layer components suddenly loses to a plain .btn { color: red } that no one can find in the layer stack — the symptom of an unlayered author rule, and this page is the DevTools procedure for hunting it down, part of the Debugging Specificity Leaks workflow inside Specificity Management & Conflict Resolution.

Prerequisites

Before you start, be comfortable with a few fundamentals:

  • How layer declaration order sets precedence: a later-declared layer wins over an earlier one for normal declarations.
  • The rule that unlayered author styles behave as an implicit final layer — they are ordered after every named layer, so they win by default. This is the single fact the whole procedure exploits.
  • The canonical stack this site uses everywhere, so you know what “layered correctly” looks like:
/* The six-layer contract. Anything NOT wrapped in one of these
   names is unlayered and silently outranks all six. */
@layer reset, base, themes, components, utilities, overrides;
  • Tooling: Chrome or Edge 115+ (Styles-pane layer grouping), Firefox 115+ (layer badges), and a browser console for the enumeration script. No build step is required to diagnose.

Why “no layer” is the strongest position in the cascade

The counter-intuitive part of @layer is that the absence of a layer is not neutral — it is the top of the priority order. The browser collects all unlayered author declarations into a synthetic layer that sorts after overrides. The diagram traces where a competing declaration lands depending on whether it is wrapped in a layer.

Unlayered author styles outrank every named layer A vertical priority stack. From bottom to top: reset, base, themes, components, utilities, overrides — all named layers — then a highlighted band at the very top labelled "unlayered author styles (implicit final layer)" showing it wins over all six named layers. priority increases upward reset base themes components utilities overrides unlayered author styles (implicit final layer) ← always wins lowest priority

The practical consequence: you cannot out-specify an unlayered rule from inside a named layer. A selector like #app .modal .btn with weight (1,2,0) in components still loses to a bare .btn in the unlayered band. The only fix is to move the offending rule into a layer — which is exactly what the steps below locate and do.

Step-by-step procedure

Step 1 — Reproduce the leak on the winning element

Select the mis-styled element in the Elements panel and look at which declaration is actually applied. If your intended rule is crossed out and the winner has no layer affiliation, you have an unlayered leak rather than a specificity or source-order problem.

/* What you authored — correctly layered, zero specificity by design */
@layer components {
  :where(.btn) { color: var(--color-on-surface, #111); }
}

/* What is leaking — plain, unlayered, loaded from some other file */
.btn { color: red; }   /* implicit final layer → beats components */

What this does: Establishes the diagnosis category. A crossed-out layered rule plus an un-annotated winner means the cascade is being decided at the layer axis, not by calculating selector weight — so chasing specificity would waste your time.

Step 2 — Read Chrome’s Styles-pane layer grouping

In Chrome or Edge DevTools, open Elements → Styles. Rules that belong to a layer are printed under a small grey Layer row (for example Layer components). Scroll to the winning declaration: if it has no Layer row above it, it is unlayered.

Styles pane, reading top-to-bottom (top = highest priority):

  element.style { }
  .btn                     ← NO Layer row → UNLAYERED, this wins
      color: red;
  Layer overrides
  Layer utilities
  Layer components
      :where(.btn)  color: (crossed out)

What this does: Turns an invisible cascade rule into a visible label. Chrome renders unlayered author rules without any Layer heading and places them above the named-layer groups, so the missing heading is the tell. Click the Layer row itself to open the layer tree and see the full registered order.

Step 3 — Confirm with Firefox layer badges

Open the same element in Firefox DevTools under Inspector → Rules. Firefox tags every layered rule with a coloured @layer badge that names the layer. A rule with no badge is unlayered.

Firefox Rules view:

  .btn { color: red; }              ← no badge → unlayered winner
  .btn  @layer components  { … }    ← badge names its layer, overridden

What this does: Gives you a second, independent confirmation. Because the two engines expose layer membership differently — Chrome via a heading row, Firefox via an inline badge — cross-checking rules out a DevTools display quirk and confirms the rule is genuinely unlayered rather than layered-but-mislabelled.

Step 4 — Enumerate every unlayered rule from the console

Manual inspection finds one leak; a script finds all of them. Paste this into the console to walk every stylesheet and report each rule whose parentRule is not a CSSLayerBlockRule.

// list-unlayered-rules.js — run in the DevTools console
// WHY: a rule is layered only if some ancestor rule is a CSSLayerBlockRule.
//      Anything else (top-level, or nested only in @media/@supports) is unlayered.
function isInsideLayer(rule) {
  for (let r = rule.parentRule; r; r = r.parentRule) {
    // CSSLayerBlockRule is the DOM type for `@layer name { ... }`
    if (r.constructor.name === 'CSSLayerBlockRule') return true;
  }
  return false;
}

const leaks = [];
for (const sheet of document.styleSheets) {
  let rules;
  try { rules = sheet.cssRules; }        // cross-origin sheets throw — skip them
  catch { console.warn('Skipped (CORS):', sheet.href); continue; }

  const walk = (list) => {
    for (const rule of list) {
      // Only style rules can leak; drill into grouping rules for nested ones
      if (rule.cssRules) walk(rule.cssRules);
      if (rule instanceof CSSStyleRule && !isInsideLayer(rule)) {
        leaks.push({ selector: rule.selectorText, source: sheet.href || '<inline/injected>' });
      }
    }
  };
  walk(rules);
}
console.table(leaks);

What this does: Produces a complete inventory of unlayered author rules with their selector and source file, including styles injected at runtime by CSS-in-JS or third-party widgets (they appear as <inline/injected>). Cross-origin sheets that block cssRules are reported as skipped so you know to audit them separately.

Step 5 — Assign each leaked rule to a layer

For every row the script returned, move that CSS into the correct layer. If you own the file, wrap its rules in an @layer block; if you only control the import, annotate the @import.

/* entry.css — bring the leaking stylesheet back into the ordered cascade */

/* WHY: the layer() modifier wraps EVERY rule in widget.css inside
   @layer components, so none of them stay in the implicit final layer */
@import url("widget.css") layer(components);

/* For a rule you own, wrap it directly instead */
@layer components {
  :where(.btn) { color: var(--color-on-surface, #111); }
}

What this does: Removes the rule from the implicit final layer and files it under a named layer that obeys your declaration order. Once inside components, the rule competes on layer position like everything else, so overrides and utilities can beat it again as intended.

Step 6 — Re-verify the computed origin

Reload and re-select the element. In Chrome’s Styles pane the winning declaration should now carry a Layer row with the expected name; in Firefox it should show the matching @layer badge.

Styles pane after the fix:

  Layer overrides
  Layer utilities
  Layer components
      :where(.btn)  color: var(--color-on-surface)   ← now the winner, labelled

What this does: Confirms the leak is closed. A labelled winner proves the rule re-entered the cascade at the intended layer; if any declaration still shows no Layer row, Step 4’s inventory has remaining entries to file.

Verification

Beyond eyeballing the Styles pane, three checks give you a durable signal.

Computed tab origin trace (Chrome): Open Elements → Computed, expand the affected property (for example color), and confirm the sourced rule sits under a named layer. If the origin has no layer, the leak persists.

Console assertion: Re-run the list-unlayered-rules.js script from Step 4. A clean codebase returns an empty table for your own stylesheets; the only acceptable remaining entries are intentional (for example, a debug overlay you deliberately keep unlayered).

Stylelint guard for regressions: Prevent new unlayered @imports from sneaking back in.

{
  "rules": {
    "no-invalid-position-at-import-rule": true,
    "no-duplicate-at-import-rules": true
  }
}
# WHY: fail the build if an @import lands after a rule (which silently
#      voids its layer() annotation) or a bare @import creeps in
npx stylelint "src/**/*.css" --max-warnings 0

Troubleshooting

The winning rule has no Layer row but you cannot find it in any .css file : It is almost certainly injected at runtime. A CSS-in-JS library (styled-components, Emotion) or a third-party embed appends a <style> element with plain rules. The Step 4 script reports these with source <inline/injected>. Configure the library to emit into a layer, or wrap the mount point, rather than searching source files that do not contain the rule.

A @import ... layer(name) still shows the rules as unlayered : The layer() modifier is ignored when the @import is not at the top of the stylesheet. Any style rule, @media block, or even a bare selector above the @import voids the annotation. Move all @import statements to the very top, after only @charset and @layer statements.

DevTools shows a Layer row but the rule still loses to something invisible : The invisible winner is likely !important or an inline style attribute. !important inverts layer order, so an important declaration in an earlier layer can beat a normal declaration in a later one — check the role of !important in layers. Inline styles beat all author layers regardless.

The console script throws or returns nothing on a cross-origin stylesheet : Reading cssRules on a stylesheet served from another origin throws a SecurityError; the script catches this and logs Skipped (CORS). Those sheets must be audited at their source, or re-served same-origin, because the browser will not expose their rules to script.

Firefox shows a badge but Chrome shows no Layer row for the same rule : The rule is layered — trust the Firefox badge. Older Chrome builds only render the Layer row in the Styles pane for the topmost matching rule of each layer; update to Chrome 115+ where grouping is exhaustive, or rely on the Computed tab origin trace instead.

Complete working example

This self-contained document reproduces a leak and then closes it, so you can watch the Styles pane change. Save it as an .html file and open DevTools on the button.

<!doctype html>
<html lang="en">
<head>
<style>
  /* STEP 3 (fundamentals): declare the canonical order up front */
  @layer reset, base, themes, components, utilities, overrides;

  @layer base {
    :root { --color-on-surface: #111; }
    body  { font-family: system-ui, sans-serif; padding: 2rem; }
  }

  @layer components {
    /* Zero specificity by design — layer position is meant to decide */
    :where(.btn) {
      color: var(--color-on-surface);
      border: 1px solid currentColor;
      padding: 0.5rem 1rem;
      border-radius: 6px;
      background: transparent;
    }
  }

  /* ── THE LEAK ─────────────────────────────────────────────
     This rule is NOT wrapped in @layer, so it lands in the
     implicit final layer and beats @layer components above.
     In DevTools it shows NO Layer row / NO @layer badge. */
  .btn { color: red; }

  /* ── THE FIX ──────────────────────────────────────────────
     Comment out the leak above and enable this block instead:
     the rule now competes inside overrides, and because
     :where(.btn) in components is zero-specificity, this
     labelled rule wins by LAYER position, not by weight. */
  /* @layer overrides {
       .btn { color: teal; }
     } */
</style>
</head>
<body>
  <button class="btn">Inspect me</button>
  <script>
    // Run the enumerator to see the leak reported in the console
    function isInsideLayer(rule) {
      for (let r = rule.parentRule; r; r = r.parentRule) {
        if (r.constructor.name === 'CSSLayerBlockRule') return true;
      }
      return false;
    }
    const leaks = [];
    for (const sheet of document.styleSheets) {
      let rules; try { rules = sheet.cssRules; } catch { continue; }
      for (const rule of rules) {
        if (rule instanceof CSSStyleRule && !isInsideLayer(rule)) {
          leaks.push({ selector: rule.selectorText });
        }
      }
    }
    console.table(leaks);   // → shows ".btn" while the leak is active
  </script>
</body>
</html>

Toggle the leak block off and the fix block on, reload, and the button’s color switches from the unlayered red to the layered teal — with a Layer row now visible in the Styles pane.

FAQ

Why do unlayered author styles beat rules inside a named @layer?

The cascade treats unlayered author styles as an implicit final layer ordered after every named layer. Because later layers win over earlier ones for normal declarations, any rule written outside an @layer block sits above reset, base, themes, components, utilities, and overrides combined. A zero-specificity unlayered selector therefore beats a high-specificity selector inside your components layer — which is why calculating selector weight cannot resolve the conflict.

Can DevTools show me which layer a winning declaration came from?

Yes. Chrome DevTools prints a Layer row above each grouped block in the Styles pane, and the Computed tab links each property to the rule that set it. Firefox shows a @layer badge next to layered rules in the Rules view. In both browsers, a winning rule that shows no layer affiliation is unlayered — that absence is the diagnosis.

Does a runtime-injected <style> tag count as unlayered?

Almost always yes. A <style> element injected by a CSS-in-JS runtime or a third-party widget emits plain rules with no @layer wrapper, so they enter the implicit final layer and override your named layers. The console enumeration script catches these because it walks every stylesheet in document.styleSheets, including dynamically inserted ones — they appear with source <inline/injected>.