For a CSS component library shared by several teams, how would you choose between @scope, build-time class-name hashing, and shadow DOM as the style-encapsulation strategy, and what does each actually guarantee?

## Decide by what can go wrong, not by what is newest The three mechanisms sit at different layers — build tooling, the cascade, and the DOM — and defend against different failures. Naming them precisely is most of the answer. ### Build-time class hashing Authored class names are rewritten into generated unique ones, and the markup is updated to match. *Guarantees:* no two components can collide on a name, enforced by the compiler rather than by discipline. Zero runtime cost — the browser sees ordinary classes. *Does not guarantee:* anything about selectors that do not use your class names. A global `button { … }`, a reset, a utility framework, or a consumer's `.sidebar a` still matches your elements. It also does nothing about inheritance, and it is only as strong as the coverage of the rewriting step, so any hand-written global escape hatch is a hole. *Costs:* a build step, and a mapping between authored names and emitted ones that debugging tools and humans have to see through. ### `@scope` A cascade-level boundary: rules inside the block may only match a subtree, optionally with a hole cut by a `to (...)` limit, and ties between nested scopes are broken by proximity rather than source order. *Guarantees:* your rules cannot escape the subtree you named; content you do not own (slotted, CMS-authored, a nested instance of the same component) can be excluded explicitly; narrowing no longer costs specificity, because the prelude does not add weight to the rules inside. *Does not guarantee:* protection from anything outside. It is strictly one-way. *Costs:* browser support is recent — Chrome and Edge from late 2023, Safari and Firefox during 2024 — and an engine that does not know the at-rule discards the entire block, so load-bearing rules need a baseline underneath. ### Shadow DOM The component's internals live in a separate tree with its own style scope. *Guarantees:* two-way isolation of selector matching. Outer selectors do not match inside; inner ones do not leak out. This is the only option on the list that survives a page whose CSS you do not control. *Does not guarantee:* immunity from everything. Inherited properties still flow in from the host, custom properties are deliberately pierceable — that is how theming works — and `::part()` exposes whatever the author chose to expose. Content projected from the light DOM continues to be styled by the outer page's rules. *Costs:* the highest. Global resets and font rules must be re-supplied inside each boundary, theming has to be designed up front through custom properties and parts rather than discovered later, and tooling that assumes a single flat document stops holding. ## The decision I would ask three questions. **Who else's CSS runs on this page?** If the answer is "only ours", the threat is accidental collision and accidental reach-in from our own code — a class of problem hashing and `@scope` handle at a fraction of the cost. If the answer is "a host page we do not control", nothing below shadow DOM is honest: any convention can be defeated by a stylesheet that never heard of it. **Does the component wrap content it does not own?** That is the specific case `@scope`'s limit was designed for, and neither hashing nor a naming convention can express it. A component that renders arbitrary consumer markup should scope with a lower boundary regardless of what else it uses. **How much theming freedom do consumers need?** Encapsulation strength and theming freedom trade off directly. Shadow DOM forces you to design the theming surface in advance — custom properties and exposed parts — and consumers get exactly that surface and nothing else. A flat document lets them override anything, which is both the feature and the risk. ## Composing rather than choosing These are layers, not alternatives, and the strongest real answer usually combines them: hashing or a naming convention to remove collisions, `@scope` for the components that wrap foreign content and for nested-instance theming, a deliberately global layer for tokens, resets and typography, and shadow DOM reserved for the widgets that genuinely cross an ownership boundary. The mistake to argue against is uniformity — applying the heaviest mechanism everywhere for consistency, then spending the next year re-plumbing theming through it. ## What none of them do Inheritance crosses every one of these boundaries. A component that never declares `color` takes it from its host, shadow root or not. If a component must look identical in any surroundings, the only reliable answer is to declare the inherited properties it depends on rather than to reach for a stronger boundary.