Specificity Audit for Legacy CSS Projects

When a legacy codebase’s ID selectors and !important flags start overriding your new @layer components without warning, you need a methodical audit — this page walks through the full procedure, as part of the Debugging Specificity Leaks workflow in Specificity Management & Conflict Resolution.

Prerequisites

Before starting, ensure you are comfortable with:

• How layer declaration order works — a later-declared layer always wins over an earlier one for normal (non-!important) declarations.
• What a specificity tuple (a,b,c) means: a counts IDs, b counts classes/attributes/pseudo-classes, c counts type selectors and pseudo-elements.
• Tooling required: Node.js ≥ 18, postcss and postcss-selector-parser as dev dependencies, stylelint ≥ 15 with stylelint-selector-specificity plugin.

The audit pipeline at a glance

The four stages below convert an opaque legacy codebase into a predictable layered architecture. Each stage has a clear input and output so you can run them incrementally across sprints.

Step-by-step procedure

Step 1 — Extract all selectors with an AST parser

Parse the entire legacy stylesheet using a PostCSS script. The output is a CSV you can sort and filter without touching the source files.

// audit-specificity.mjs
// WHY: PostCSS gives us a real AST, not a regex — it handles comments,
//      @media blocks, and nested @layer blocks correctly.
import postcss from 'postcss';
import parser  from 'postcss-selector-parser';
import fs      from 'fs';

function scoreSelector(selector) {
  let a = 0, b = 0, c = 0;
  parser(selectors => {
    selectors.walkIds(()     => a++);             // ID selectors → a
    selectors.walkClasses(() => b++);             // class selectors → b
    selectors.walkAttributes(() => b++);          // attribute selectors → b
    selectors.walkPseudos(node => {
      const name = node.value.replace(/^:+/, '');
      // :where() always contributes 0; :is()/:not()/:has() take their argument's score
      if (!['where','is','not','has'].includes(name)) b++;
    });
    selectors.walkTags(node => {
      if (node.value !== '*') c++;                // type selectors → c; * is 0
    });
  }).processSync(selector);
  return { a, b, c };
}

const css  = fs.readFileSync('./dist/bundle.css', 'utf-8');
const root = postcss.parse(css);
const rows = [];

root.walkRules(rule => {
  // WHY: split compound selectors before scoring; each part is scored independently
  rule.selector.split(',').forEach(sel => {
    const s   = sel.trim();
    const { a, b, c } = scoreSelector(s);
    const imp = /!important/.test(rule.toString());
    rows.push({ selector: s, a, b, c, important: imp, source: rule.source?.input?.file });
  });
});

// WHY: sort descending so the worst offenders appear first in the report
rows.sort((x, y) => y.a - x.a || y.b - x.b || y.c - x.c);
console.log('selector,a,b,c,important,source');
rows.forEach(r =>
  console.log(`"${r.selector}",${r.a},${r.b},${r.c},${r.important},${r.source}`)
);

What this does: Produces a CSV like "#app .sidebar .nav-item.active",1,2,1,false,src/nav.css. Every selector is scored; the file is not modified.

Run it:

node audit-specificity.mjs > specificity-report.csv

Step 2 — Triage the matrix

Open the CSV and sort by a (ID count) descending, then by b descending. Any row where a > 0 or b > 3 enters the remediation queue; rows where important = true are highest priority regardless of score.

Flag the following selector patterns for immediate action:

• a > 0 — ID selectors (#app, #root); IDs cannot appear in a design system’s class-based architecture.
• b > 3 — three or more classes/attributes in one compound selector; indicates cascaded patches, not intentional design.
• important = true — !important should be absent from author styles once the role of !important in layers is understood; in legacy code it almost always masks a cascade architecture problem.

What this does: The triage step converts an overwhelming list into a prioritised remediation queue. You now know exactly how many rules need work before you touch a single line of CSS.

Step 3 — Declare the target @layer order

Write one upfront @layer statement in the root stylesheet — loaded before every other CSS file. This locks the cascade contract so no later @layer block can shift the priority order.

/* root.css — must be the first stylesheet the browser parses */

/* WHY: declaring all layers here in one statement establishes precedence
   before any rule is authored; later @layer blocks only add rules,
   they cannot reorder layers already declared */
@layer reset, base, theme, components, utilities, legacy;

/* legacy sits last during the migration window so existing styles
   keep winning over the new architecture until you explicitly promote them.
   Once migration is complete, remove legacy from this list entirely. */

What this does: The browser registers the layer order at parse time. Rules in utilities beat rules in components for the same property, regardless of selector specificity — no !important required.

Step 4 — Wrap legacy imports in a dedicated layer

Import the legacy stylesheet with the layer() keyword so its rules are sandboxed and cannot override any higher-priority layer.

/* root.css, after the @layer declaration */

/* WHY: @import with layer() wraps every rule in legacy-styles.css
   inside @layer legacy — the file itself is unchanged */
@import url('legacy-styles.css') layer(legacy);

/* WHY: normalize.css belongs in reset, not legacy — it should be
   the baseline, not an opaque legacy artefact */
@import url('normalize.css') layer(reset);

@layer components {
  /* New architecture rules go here; they beat legacy because
     components is declared before legacy in the @layer statement */
  .btn { padding: 0.5rem 1rem; background: var(--color-primary); }
}

What this does: Every rule in legacy-styles.css is now inside @layer legacy. Because legacy is declared last, legacy rules still win during the transition — preserving visual parity — while the new architecture builds up beneath them. As you refactor individual rules out of legacy and into their correct layers, the legacy wins shrink.

Step 5 — Refactor selectors from the remediation queue

Work through the remediation queue from Step 2. Apply three transformations in order: replace IDs with classes, flatten nesting, then remove !important.

/* BEFORE — selector from the remediation queue:
   (1,2,1): ID + 2 classes + element; wins over anything in @layer */
#app .sidebar .nav-item.active { color: #333; }

/* AFTER — two transformations applied: */

@layer components {
  /* WHY: .nav-item--active replaces both #app and .active;
     BEM modifier keeps semantics without adding weight */
  .nav-item--active {
    /* WHY: a design token keeps the value auditable;
       specificity is now (0,1,0) — just one class */
    color: var(--color-nav-active, #333);
  }
}

For each rule in the queue, determine which architectural layer it belongs to:

• Element defaults and resets → reset or base
• Design token definitions → theme
• Component variants and states → components
• Single-property overrides applied via class → utilities
• Context-specific patches that survive the audit → overrides (a sub-layer of utilities or an explicit overrides layer)

/* WHY: :where() zeroes the specificity of a migrated legacy selector
   so the layer position — not the selector — determines cascade priority.
   Use this during migration when you cannot yet rename the selector. */
@layer components {
  :where(#app .sidebar .nav-item.active) {
    color: var(--color-nav-active, #333);
  }
}

What this does: Each refactored rule lowers the effective specificity floor and moves a rule out of @layer legacy into an intentional architectural layer. Over multiple sprints the legacy layer empties.

Step 6 — Verify with Stylelint and visual regression

After each migration batch, run two checks before opening a pull request.

Stylelint configuration:

{
  "plugins": ["stylelint-selector-specificity"],
  "rules": {
    "plugin/selector-max-specificity": "0,3,0",
    "declaration-no-important": [true, { "severity": "error" }],
    "selector-max-compound-selectors": 3
  }
}

# WHY: --max-warnings 0 makes any violation a hard CI failure
npx stylelint 'src/**/*.css' --max-warnings 0

DevTools trace:

1. Open Chrome DevTools → Elements → Computed.
2. Click any property (e.g. color) to expand its cascade origin.
3. The winning declaration shows its layer name in square brackets (e.g. [components]). Crossed-out declarations are overridden; their layer labels explain why.
4. If a rule from [legacy] is still winning where you expect [components] to win, either the refactoring step was not applied or the @import order is wrong in the root stylesheet.

Visual regression:

Run screenshot comparisons with Playwright, Chromatic, or Percy. Any unintended cascade shift from a misassigned layer will appear as a pixel diff before the PR merges.

What this does: Stylelint enforces the specificity ceiling automatically so no new high-weight selector can enter the codebase. DevTools confirms the cascade origin of the winning rule. Visual regression catches anything the static analysis misses.

Troubleshooting

Legacy rule still wins over a components rule after wrapping it in @layer legacy : The winning rule is likely not inside the @import url(...) layer(legacy) import — it may be defined in a <style> block, an inline style attribute, or a second stylesheet loaded without a layer() annotation. Unlayered author styles sit above all @layer declarations. Audit every CSS entry point: check <link> tags, @import statements, and any CSS-in-JS that injects styles at runtime.

@import url(...) layer() is not wrapping the rules : The layer() modifier on @import requires the @import to appear before any other rule (other than @charset and @layer statements) in the stylesheet. If a rule or selector appears above the @import, the browser ignores the layer() annotation. Move all @import statements to the top of root.css.

Specificity score shows (0,0,0) for a selector that looks weighted : The extraction script counts structural selector parts, but pseudo-elements (::before, ::after) and the universal selector (*) contribute zero to specificity — this is correct per the spec. Re-check the selector manually if the computed style in DevTools disagrees with the script’s output.

!important in the legacy layer is still winning after the migration : This is the !important cascade-inversion trap. When !important is used, layer priority reverses — so !important in an earlier-declared layer beats !important in a later-declared layer. An !important rule in @layer legacy (declared last) therefore loses to an !important rule in @layer reset (declared first). The fix is to remove !important from both the legacy rule and the overriding rule, then let the layer order alone determine priority.

Stylelint flags rules in @layer legacy that you cannot refactor yet : Add an inline disable comment scoped to that rule block and add a TODO linking to the ticket: /* stylelint-disable-next-line plugin/selector-max-specificity -- TODO: tracked in #1234 */. Track these as technical debt in the sprint backlog, not as permanent suppressions.

Complete working example

Copy this self-contained file as a starting point. It covers all six audit steps in a single root stylesheet and illustrates the before/after refactoring pattern.

/* ============================================================
   root.css — load this before all other stylesheets
   ============================================================ */

/* STEP 3: lock the layer order first; later blocks cannot change it */
@layer reset, base, theme, components, utilities, legacy;

/* STEP 4: sandbox the legacy file; its rules live inside @layer legacy */
@import url('legacy-styles.css') layer(legacy);
@import url('normalize.css')     layer(reset);

/* ── reset ────────────────────────────────────────────────── */
@layer reset {
  /* WHY: box-sizing here prevents legacy padding rules
     from causing layout shifts during migration */
  *, *::before, *::after { box-sizing: border-box; }
  body { margin: 0; }
}

/* ── theme ────────────────────────────────────────────────── */
@layer theme {
  :root {
    /* WHY: centralising tokens means a single-value change
       propagates to every component consuming it */
    --color-primary:    #0057e7;
    --color-nav-active: #111;
    --font-weight-semi: 600;
  }
}

/* ── components ───────────────────────────────────────────── */
@layer components {
  /* STEP 5 AFTER: refactored from #app .sidebar .nav-item.active
     Specificity: (0,1,0) — one BEM modifier class
     WHY: layer position (components beats legacy) replaces
     the old specificity arms race */
  .nav-item--active {
    color: var(--color-nav-active);
    font-weight: var(--font-weight-semi);
  }

  /* STEP 5 TRANSITION: :where() zeroes the legacy selector's weight
     while the DOM is still using the old class names;
     remove once the HTML is updated to .nav-item--active */
  :where(#app .sidebar .nav-item.active) {
    color: var(--color-nav-active);
    font-weight: var(--font-weight-semi);
  }

  /* Refactored card title: was #main .content .card .title { font-weight: bold !important } */
  .card__title {
    font-weight: var(--font-weight-semi);
    /* WHY: token reference keeps the value auditable in design tooling;
       !important removed because this layer beats legacy without it */
  }
}

/* ── utilities ────────────────────────────────────────────── */
@layer utilities {
  /* WHY: single-purpose utility classes belong here;
     they beat components so .u-sr-only genuinely hides regardless
     of which component it is applied to */
  .u-sr-only {
    position: absolute;
    width: 1px; height: 1px;
    overflow: hidden;
    clip: rect(0 0 0 0);
    white-space: nowrap;
  }
}

/* ── legacy ───────────────────────────────────────────────── */
/* @layer legacy is populated entirely by @import above.
   As rules are refactored into components/utilities, they are
   removed from legacy-styles.css. When the file is empty, drop
   the @import and remove 'legacy' from the @layer declaration. */

FAQ

Related

• Debugging Specificity Leaks — parent cluster covering diagnostic workflows for cascade conflicts
• Specificity Management & Conflict Resolution — root section for selector weight, conflict resolution, and @layer strategy
• Calculating Selector Weight in Layers — how the browser computes (a,b,c) tuples within and across layers
• Understanding Layer Declaration Order — why the sequence of the upfront @layer statement is the single source of truth for cascade priority
• The Role of !important in Layers — how !important inverts layer priority and why it rarely belongs in a refactored architecture