The cascade contract

The order

/* declared once, first, in every dist file: */
@layer bo-reset, bo-tokens, bo-primitives, bo-components, bo-utilities;

/* YOUR css — written outside any layer — always wins: */
.bo-btn { border-radius: 2px; }   /* beats the component layer, no !important */

• reset → tokens → primitives → components → utilities: utilities win over components (the one Tailwind-ism kept — a small curated set, not a system).
• The layer-order statement is byte-identical in every dist file, and re-declaring an existing order is a no-op — any à-la-carte import combination yields the same cascade.
• Re-branding = remapping the semantic token tier in your unlayered file; see Theming. Never override component classes for brand.

Stacking (z-index) — a different mechanism, don't conflate them

@layer above decides which RULE wins when two selectors both match the same element — it never affects paint order between DIFFERENT elements. z-index decides what's drawn on top of what — it has no opinion on which rule wrote a property. A page can get the cascade layer completely right and still show one element behind another it should be in front of, because that's the other system entirely — precisely what happened building the object page pattern: its own sticky title bar (page-level chrome) was losing a stacking fight to an ordinary component nested inside it, a table's sticky column header, because the page reached for an arbitrary z-index: 2 instead of the framework's actual scale.

The rule: every position: sticky or position: fixed element that isn't a plain in-flow box reaches for a token from this table — never a bare number. If none fits, that's a sign a new tier belongs here, not that this element gets to invent one. Where a PATTERN's own page-level sticky chrome collides with a component it contains (the object-page shape above): the page-level chrome wins, because it is the screen's own navigation, one level above anything nested in it — --bo-z-sticky-page exists for exactly that tier, sitting above every component-internal sticky value it might collide with, below --bo-z-dropdown (a dropdown opened from inside the page must still float above the page's own chrome) and --bo-z-toast (always wins, globally).

What this buys at screen #200

Overrides stay one-liners instead of specificity ladders; framework upgrades can't silently outrank app CSS (layered can never beat unlayered); and audits are mechanical — anything inside @layer bo-* is ours, anything outside is yours.

One sharp edge: an unlayered reset you didn't write (Tailwind v3 preflight, normalize) wins by the same rule and strips components — wrap it in a lower layer; recipe + live proof in Troubleshooting.