Debug CSS Specificity Wars with the Cascade Layers Toolbox

1. Read the winner and every loser in the Styles pane.

echo "DevTools > Elements > select button > Styles: crossed-out rules rank below the winner; hover each selector to see its specificity (a,b,c) triple"

Expected output: The pane shows the winning declaration and each overridden rule crossed out with its specificity triple, for example .btn.primary (0,2,0) beating .card .btn (0,2,0) only by source order.

2. Compute specificity by hand to confirm the tool reading.

node -e "const sp=(s)=>{const i=s.match(/(^|\s)[#.][\w-]+|:[a-z-]+(?!.*\()/g)||[];let a=0,b=0,c=0;s.replace(/#[\w-]+/g,()=>{a++;return ''}).replace(/[.][\w-]+|:([a-z-]+)/g,(m,g)=>{g?c++:b++;return ''}).replace(/(^|\s|>)?[a-z][\w-]*/gi,()=>{c++;return ''});console.log(s,(a,b,c))}; sp('#app .card .btn.primary'); sp('.card .btn'); sp('button.btn')"

Expected output: The script prints specificity triples per selector, matching the DevTools hover values and making the comparison arithmetic instead of folklore.

3. Defuse existing !important escalation before refactoring.

/* the arms race, defused by matching and exceeding ONCE: */
/* before: .a { color: red !important } .b { color: blue !important } */

/* step 1: both sides drop !important (one PR, both devs agree) */
.a { color: red; }
.b { color: blue; }

/* step 2: the conflict is decided by layer order instead */

Expected output: The trade agreement removes all !important on the contested property in one coordinated change, preparing the ground for a structural fix.

4. Resolve classes of conflicts by design with cascade layers.

/* layers: earlier = LOWER priority. One decision, no per-selector fights */
@layer reset, theme, components, utilities, overrides;

@layer components {
  .btn { color: var(--btn-fg); }
  .card .btn { color: var(--card-btn-fg); }   /* (0,2,0), fine inside layer */
}

@layer utilities {
  .text-red { color: red; }    /* beats ANY components rule: by layer */
}

/* zero-specificity resets that still lose politely: */
@layer reset {
  :where(a) { color: inherit; }  /* (0,0,0) even with the element part */
}

Expected output: Conflicts between themes, components, and utilities resolve by declared layer order, and no selector needs to game its specificity to win.

5. Verify the winner is the intended one and stays stable.

echo "reload, confirm the button shows the designed color; then toggle .text-red and confirm the utility wins by layer, not by !important"; grep -rn "!important" src/styles/ | wc -l

Expected output: The styled element shows the designed color, toggling the utility overrides by layer order as intended, and the repository-wide !important count drops to near zero.

Problem

A framework injects styles above my layer

Solution

Unlayered styles beat all layers; if the framework ships unlayered CSS, declare your layers and put framework styles into a low-priority layer via import with layer(), or match its specificity once in overrides.

Problem

Inline styles or JS-set styles beat everything

Solution

Only !important in a stylesheet can beat inline style; prefer removing the inline style, or if unavoidable, scope one targeted !important in the overrides layer as the documented exception.

Problem

Specificity tool triple disagrees with DevTools

Solution

Pseudo-classes count as class-level but pseudo-elements count as element-level; re-check the selector for :hover versus ::before, which is the most common hand-count error.