Why this theme has no cascade layers

Cascade layers are a good idea. They give you a way to say this whole stylesheet is less important than that one without reaching for !important. I added them to this theme early, and then spent an afternoon working out why a heading was rendering as a default blue link.

The bug was a tie, not a weight

The theme’s header title had a rule at one class of specificity. WordPress’s own global styles had a rule at exactly the same specificity, and it was winning. Not because it was heavier — because it was printed later, and unlayered.

:root :where(a:where(:not(.wp-element-button))) { color: #1d4ed8 }  /* WordPress, unlayered */
.fsd-header__title { color: #14171c }                              /* theme, layered   */

Why source order decided it

Two rules, the same specificity, neither marked important. The cascade falls through to source order and the later one wins. Layers sit above source order in that list, which is exactly why an unlayered rule beats a layered one no matter where it is printed.

What replaced them

Section comments and a deliberate reading order. Within a single unlayered stylesheet, ties are resolved by source order, and source order is something you can see while you are reading the file.

• Reset and tokens first, so everything after them can override.
• Layout primitives next, since they are structural rather than visual.
• Components last, because a component is the most specific thing on the page.

{
  "settings": {
    "color": { "defaultPalette": false },
    "typography": { "defaultFontSizes": false },
    "spacing": { "defaultSpacingSizes": false }
  }
}

The cost, stated plainly

Reordering that stylesheet is now a behaviour change, and a future contributor will not guess that. That is a real cost, and it is the honest reason the anti-pattern list in this repository exists.

A layer boundary you cannot see is worse than an order you have to remember, because at least the order is written down.