[css-scoping] Proposal for light-dom scoping/namespacing with re-designed `@scope` rule

[mirisuzanne]

This would likely require additions to both CSS Scoping and CSS Cascade. See my full explainer for more details.

As I've been working on proposals around cascade layers & component queries, there is another aspect of "cascade modernization" that comes up regularly: scope. I'm aware that there is some hesitancy on the issue, since the initial specification was never implemented, and Shadow DOM was seen as a path forward (potentially a replacement). I think that time (and further development of Shadow-DOM) has helped clarify two quite different use-cases:

1. Total isolation of a DOM subtree/fragment from the host page, so that no selectors get in or out unless explicitly requested.
2. Lighter-touch component namespacing, and prioritization of "proximity" when resolving the cascade.

Shadow-DOM addresses the first, but it comes with a lot of overhead that is required for "full isolation". Meanwhile authors rely on convoluted naming conventions (like BEM) and JS tooling (such as CSS Modules, Styled Components, & Vue Scoped Styles) for the second use-case… which has been thoroughly discussed in various forms:

• Bring Back Scope
• Selector Boundaries
• CSS Namespaces

[Note: This doesn't attempt to resolve all the use-cases discussed in those threads. The discussion so far has often conflated the two approaches to scope, and I'm trying to divide them out. I think that still leaves a number of "isolation-first" cases that would best be addressed with changes that build on top of shadow-DOM - such as these ideas explored by Yu Han.]

Re-introducing @scope <selector> { ... } with a few adjustments…

1. Provide a "lower boundary" or "slot" syntax

This would make it possible to scope fragments rather than entire DOM sub-trees. @giuseppeg has suggested a syntax that I think is a good starting-point for more bikeshed discussion:

@scope (from: .carousel) and (to: .carousel-slide-content) {
  p { color: red }
}

In my mind, only the first ("from") clause should be required, and may not need explicit labeling. It would likely accept a single (complex) selector:

@scope (.media-block) {
  img { border-radius: 50%; }
}

In terms of selector-matching, this would be the same as .media-block img, but with slightly different cascade implications (see below). The second ("to") clause would be optional, and accept a list of selectors that represent lower-boundary "slots" in the scope. The targeted lower-boundary elements are included in the scope, but their descendants are not:

@scope (.media-block) to (.content) {
  img { border-radius: 50%; }
  .content { padding: 1em; }
}

Which would only match img and .content inside .media-block -- but not if there are intervening .content between the scope root and selector target. This follows the current selector-scoping behavior of various popular tools.

I'm not convinced that to is necessarily the right keyword (others have proposed until) or if we should even consider using a functional syntax, or calling calling the lower boundary "slots":

@scope root(.media-block) slots(.content) { /* ... */ }

More discussion would be useful.

2. Make the cascade effects of scoping much less intrusive (weighted below specificity)

When scopes do overlap, it's useful to recognize the proximity of a scope (inner scope takes precedence) in the cascade. This is not currently represented in CSS. Descendant selectors rely on source order rather than proximity:

/* link colors for light and dark backgrounds */
.light-theme a { color: purple; }
.dark-theme a { color: plum; }

When these color themes are nested, the dark theme will always take precedence:

<div class="dark-theme">
  <a href="#">plum</a>

  <div class="light-theme">
    <a href="#">also plum???</a>
  </div>
</div>

Both shadow DOM and the original spec give scoped context a very powerful impact on the cascade — overriding even specificity. The original spec also inverted scope-layering for !important declarations. This follows the logic of more highly-isolated use-cases, where there is more clear distinction between the inner scope and the outer host. But in the more common lightly-scoped cases, a more nuanced interplay between specificity and scope is helpful. Most existing tools only add minimal cascade weight to scoped selectors, like a single attribute selector.

I propose re-adding "scope proximity" to the cascade specification after/below selector specificity, but above/before source-order. That would help resolve our example above:

@scope (.light-theme) {
  a { color: purple; }
}

@scope (.dark-theme) {
  a { color: plum; }
}

<div class="dark-theme">
  <a href="#">plum</a>

  <div class="light-theme">
    <a href="#">purple</a>
  </div>
</div>

While still allowing more specific selectors to override scope when desired.

If authors desire more layering impact similar to the initial spec, that is now available using Cascade Layers — and the two features can be combined.

A path forward

This still needs a lot of work, but my goal here is to open discussion around a path forward for light-DOM scope/namespacing. I have a much more detailed explainer for my thought-process — but there are a lot of open questions, and I'd like to:

• gauge CSSWG interest before going deeper
• get more people involved with fleshing out the details

Happy for comments, thanks!

[nemzes]

Love the proposal. A bit of bike-shedding to get things started: what about "within" and "without" instead of "from" and "to"? It's not the most common use of "without", but to me it sounds like the most fitting word. "To" and "until" imply linearity, which can be misleading.

[nemzes]

How would scoped selectors like :hover and :focus-within behave if the triggering element is a child that is not in scope?

[nex3]

(Context: I'm the tech lead for CSS infrastructure at Google)

This sort of declarative, light-DOM scoping would be very useful for our widest use-case of component-based styles that may either be rendered server-side or client-side, and that sometimes need escape hatches to do global styles. We would probably take measures to enforce that component scopes corresponded one-to-one with templates, so that we could reason locally about those styles for various optimization passes. This is something that's historically been very difficult to do safely in CSS, so a scope mechanism enabling it is very exciting.

[jimmyfrasche]

Re https://github.com/oddbird/css-sandbox/blob/main/src/scope/explainer.md#can-scoped-selectors-reference-external-context

If "scoped selectors should be otherwise unaware of the scope" wouldn't that mean that both divs in the example below are blue?

<div class=x>
  <div class=component>
    <div class=x>
      <div class=x>x</div>
      <div class=y>y</div>
    </div>
  </div>
</div>
<style>
@scope (.component) {
  .x .x { color: blue; }
}
</style>

My preference would be for an explicit .my-host-page :scope .my-component-part (if for no other reason than to make it clear what's intended!) with just disallowing it entirely a distant second.

[css-meeting-bot]

The CSS Working Group just discussed [css-scoping] Proposal for light-dom scoping/namespacing with re-designed `@scope` rule.

The full IRC log of that discussion

<dael> Topic: [css-scoping] Proposal for light-dom scoping/namespacing with re-designed `@scope` rule
<dael> github: https://github.com//issues/5809
<dael> miriam: I have slides, but talk through without?
<miriam> https://un5m3c2mw35vpk56q3vdam34xu6g.julianrbryant.com/csswg/f2f2102/#slide-26
<dael> miriam: Link ^
<dael> [trying to see if miriam can present]
<dael> miriam: I'll talk through them
<dael> miriam: There has been several threads open about having a scoping in css
<dael> miriam: There was even attempt in 2014 to spec it. not impl.
<dael> miriam: Looking into it I found differences with shadow dom. Proposal is what is see is missing from shadow dom.
<dael> miriam: Main goals are avoiding naming conflicts and expressing memebership in a scope. Similar to what shadow dom does which gives us scope and slots. Different from ancestor b/c lower bounderties. It actually belongs to the component
<dael> miriam: A lot of tools out there try and do this manually. Putting together special selectors
<dael> miriam: Other part is trying to capture sense of proximity. A light and dark theme and I need to style links in those. If I use descendant selector the second definition take precesendce when selected. What I want is the one that is closer.
<fantasai> [slide 32]
<fantasai> [slide 33]
<dael> miriam: Why not shadow dom? Basic answer is shadow dom encapulation is high impact and dom centered. Element itself is the scope and that's hard bounderies in the dom. Strong isolation of bounderies.
<fantasai> [slide 34]
<dael> miriam: High power in the cascade as well. It overrides specificities
<fantasai> [slide 35]
<dael> miriam: Interesting proposals to improve, but don't resolve central issues. I think declaritive shadow dom is interesting. But not the same thing as we're trying to solve with views etc.
<dael> miriam: I sometimes want lower bounds, outer bounds. But I want to do that and it's a presentational decision, not semantic. I don't want it tied to dom elements. I want overlap. I want to say what's in or out
<fantasai> [slide 38]
<TabAtkins> q+ when Miriam is done to express support
<leaverou> q+
<TabAtkins> qq+
<dael> miriam: All these tools do it lower impact. It's reused across leements. Priority is handled through ownership rather then specificity
<leaverou> q-
<leaverou> q+
<fantasai> [slide 40]
<fantasai> [slide 41]
<miriam> https://un5gmtkzgjpv2j52yjjw3d8.julianrbryant.com/pastebin/MtGSIIPT/
<dael> miriam: Prop bringing back scope rule and scope pseudo class. Proposal is a syntax like &
<dael> miriam: We get @scope and add a selector for outer bounds. Optionally add a to() with any number of lower bounderies. Anything within the rule would scope between selectors
<dael> miriam: Scope selector is the root. It's implied when not used
<fantasai> [slide 42]
<fantasai> [slide 43]
<dael> miriam: I have more details about exactly how I see boundry and selector matching working. Gone through tag review on how it would work. Final piece is this triggers proximity as part of cascade. When 2 scopes overlap inner scope is the fallback to specificity. When they're equal internal scope takes presedence.
<dael> miriam: Some talk about being able to scope to a donut. Is it useful to have it as a selector in it's own right. Interesting and could look more
<astearns> ack TabAtkins
<Zakim> TabAtkins, you wanted to react to a previous speaker
<dael> TabAtkins: I'm very happy to see this. Was happy to work with miriam early on. We tried to do light dom scoping earlier but that was substantially different. It was trying to interact similar leverl of intrusiveness as shadow dom
<astearns> ack leaverou
<dael> TabAtkins: This being a low thing is a really great and useful tool that compliments shadow dom and what we're doing. I'm a big fan of it
<dael> leaverou: I would like to agree with TabAtkins this is highly needed. I support it
<dael> leaverou: Elaborating on my point, I think propo consists of 2 parts. Name spacing use cases which are nesting within this new scope rule and the prozimity prioritization. And then there's the donut scope syntax. Anything related to selection logic isbetter in selectors. That gives it a JS API which gives you access to frequently needed queries
<dael> leaverou: Worth exploring how the donut scope could be done through selectors syntax so @scoping can just have the scoping and not the selection
<dael> leaverou: Does that make sense?
<dael> fantasai: You're prop selector in addition to @scope where selctor is a limit on what's selected?
<dael> leaverou: Yes
<argyle> like `@scope .tabs - .panel {}` like this? where the dash is showing a range?
<dael> fremy: Makes a lot of sense to me
<fantasai> s/selected/selected, but doesn't affect the cascade/
<Rossen_> q?
<dael> florian: Seems worht exploring. Since interested in both parts, I'd like to first express support for the whole thing. We'll take everything here and then as we take this poss try to do donut in selectors. Don't insist on the donut thing to take this
<astearns> ack fantasai
<dael> leaverou: Both problems need solving
<TabAtkins> Hm, I'm not sure how we would work a lower-boundary into the normal selector syntax
<dael> fantasai: Question I have is, I want to understand impact on specificity. Previous @scope proposal which didn't have lower bound. Other difference is specificity, if you have more specific selector outside it overrides in the scope. In previous prop if you're inside a scope it overrides everything outside.
<dael> miriam: That's right
<TabAtkins> Currently, @scope basically *is* just a selector (allowing nesting)
<dael> fantasai: Can you explain the reasoning behind why this is the appropriate choice?
<dael> miriam: One thing, going back a ways as I teach CSS people expect this to be the default fallback. People are surprised by source order being the fallback. That was in my mind
<florian> q+
<dael> miriam: Also this is how all the tools currently work. Feels like it works well to me. Not trying to isolate strongly, trying to keep things from getting out, not from getting in
<dael> miriam: Tools do it with an added attribute now, but that only increases spec by a small amount
<dael> fantasai: This has less impact. Concerned it would cause...not give same results in a lot of cases. not convinced. When you add a class, you'd have to add more specificity.
<leaverou> +1 to fantasai's concerns. If it can be overridden by rules outside the scope, it becomes very similar to nesting which we know doesn't solve these problems
<dael> miriam: Except that the proposal has the scope root selector being added to all selector in scope so it's same as single attribute in most cases, but could be more powerful. Set root selector to ID you're adding the id to seelctor to everything inside. Can create higher weight but you have more control. Only proximity part is lower
<dael> fantasai: spec of selector in @scope condition is added to all selectors within scoped block
<dael> miriam: Right
<dael> fantasai: That wasn't clear. I don't hitnk that's a good design. The way you select element you want to be scoped shouldn't have effect on how specific selector in scope are. If you switch class to ID it can completely distroy relationship between selectors.
<TabAtkins> q+
<dael> fantasai: Where this fits in cascade I'm interested to think about. I don't htink choice of selector in @scope should have effect on cascade
<astearns> ack TabAtkins
<dael> TabAtkins: What I like about miriam design is it is virtually identical to specificity landscape, including with nesting. That means that it's as familiar as specificity in existing css including the scope inheriting into nested selectors
<dael> TabAtkins: You can override it with no specificisty selector. That would achieve same effect w/o specificity. By default you get today's behavior. That has problems, of course, but because we're in todya's model anything we do in the future doesn't have more to worry about. It's the existing model and wil interoperate
<astearns> ack florian
<dael> florian: I don't have a strong view on issue we've been discussion, but not that concerned. Compared to last time we tried this it's easier b/c less problems. We have cascade layers and shadow dom. As miriam pointed out main goal is prevent styles from leaking out. We need tor esolve conflicts, but primary goal is leaking out
<dael> florian: If you want strong isolation maybe you should use shadow dom. If you want to make sure you win you have cascade layers. We need to solvet he discussion, but unlike last time since we're not trying to solve all the problems it doesn't concern me as much
<dael> fantasai: I have strong reservations about the proposal
<nicole> q+
<dael> astearns: Are they about the specificity for the rules inside the block?
<TabAtkins> Yup, recognizing that we're already solving the "figure out which large set of styles wins" in other ways means we can focus this one on the much simpler problem of "lower bound protection" (and, for giggles, letting us give a weak notion of proximity to specificity).
<astearns> ack nicole
<dael> fantasai: Basically, everything except syntax. Also where it fits into cascade. Feel strongly spec of root selector should not be a factor in cascade. Not convinced way defined to itneract with specificity is what we want. Possible it is and I don't understand use cases, but I don't think so.
<dael> nicole: Speaking to use in design systems. You would end up with simple seelctor in root selector
<dael> nicole: I would have expected that as a part of specificitly b/c how nesting works in sass
<leaverou> q+
<fantasai> s/I don't think so/based on what I know, I don't think this is right/
<astearns> ack leaverou
<dael> nicole: Case on more complex selector in root would be more rare. I would expect they want something specific and fremy said that would be better achieved with layers. The interaction of the 2 makes sense
<fantasai> s/Also where/Where/
<dael> leaverou: Separate nesting spec that's supposed to do same as nesting in sass. If they do similar things with slight differences it will be confusing. I agree with some of fantasai concerns. WE know nesting doesn't solve scoping use cases. If things outside scope can leak in worried it won't address cases
<TabAtkins> Contra fantasai, I feel *strongly* that the root selector needs to be figured into the nested styles, because otherwise the selectors will *often* be too weak. Keeping those selectors weak *when they would auto-win anyway* (as our earlier @scope attempt did) is fine, but if we're working within the standard specificity wars, letting the container's selector add in is necessary.
<dael> fantasai: I think you want things to leak in, but leak in at a lower priority
<dael> leaverou: That's what I meant
<dael> fantasai: Prop here fusses with spec and scoping is a fallback. Previous scoping said it was higher than specificity so inner scope would win if there and outer would take effect. Shadowdom the outer scope wins.
<dael> fantasai: Both cases are different. Question is how does scoping interact with specificity
<fremy> I agree with TabAtkins here
<dael> TabAtkins: WE're solving problem of how to worry about larger scale conflicts with layers so we don't have to care as much here.
<dael> fantasai: I think layers helps a lot, but not quite the same. But yeah, can create a layer for every component. Seems overkill
<dael> leaverou: Layers are supposed to contain enitre library, not every component
<dael> TabAtkins: I don't htink you'll be worrying at that level
<dael> fantasai: Example: I have a sidebar in my page and want it to have a different color. Inverse contrast color. I have rules setting link color heading color etc. Need to override them all in my sidebar. I override the link and say it's light.
<dael> fantasai: Overall outer page has slightly different colors for links in a list. B/c that's higher specificity it overrides the sidebar.
<argyle> Sime Vidas showing donut scoping with complex `:not()` https://un5nf0fj54k46fxm3w.julianrbryant.com/weekly-platform-news-focus-rings-donut-scope-ditching-em-units-and-global-privacy-control/#the-enhanced-css-not-selector-enables-donut-scope
<dael> fantasai: So it doesn't solve the scoping problem b/c specificity
<leaverou> argyle: I've made this point too, but this fails with nested structures
<dael> TabAtkins: You're right it does not solve. You solve it using standard specificitly mechanisms or if this is a page specific modification that's what layers is designed to do. Let you separate general styles from specific styles that need to win at all costs. We've solved that
<dael> fantasai: It's not nec page specific. It could be for my whole site
<dael> florian: What's wrong with a layer
<dael> fantasai: Rest of page could have layers and now they're siblings. It's not about the loading, it's about am I in a sidebar b/c if I am they need to be more important. That's hierarchy, not which stylesheet wins
<fantasai> s/siblings/sibling layers, and ordering matters/
<leaverou> argyle: I've written more about how it fails with nested structures here: https://github.com/w3ctag/design-reviews/issues/593#issuecomment-769351277
<dael> TabAtkins: I don't agree entirely. In some cases yes, but in many cases it's not. Complexifying this by adding another strong kind of scoping will add a ton of complications. Solving in this weak way that melds cleanly and goes with the general approach is better
<dael> astearns: miriam I think you should take the strong opinions as encouragement. That everyone is digging in and has strong opinions and expressing concerns is an indication we should continue work.
<dael> astearns: I don't think we'll be able to resolve to officially work on this right now, but I think we can get there
<TabAtkins> leaverou, argyle: Yeah, current selectors are definitely just too weak to handle lower bounds.
<dael> miriam: Yes, and I was expecting this to be contentios because there are use cases all along the spectrum. That's been a challenge with scope. I went weak intentionally. There are strong pieces out there so I thought I'd go the other direction to balance out the use cases.
<dael> astearns: I think that's all the time we can give to this today
<fantasai> TabAtkins, this is adding something that's "almost the same as nesting but not quite in small ways", as Lea noted. That's more confusing than adding strong scoping that works the opposite of shadow DOM.
<dael> astearns: I don't know how much time you can spend on this miriam but feel free to create something in spec form and make separate issues for the separate concerns.

[mirisuzanne]

My scope slides are also archived as a PDF (along with the container-query proposal), for anyone interested. Scope proposal begins at slide 26.

I expected my proposal to make scope proximity less powerful than selector specificity might be surprising compared to previous proposals. But I didn't come to that proposal lightly – it's based on a lot of conversations, and research of the existing tools. In an informal Twitter poll:

What color would you expect to see on a paragraph that is matched by both these CSS rules?

@​scope (aside) {
  p { color: green; }
}

aside#sidebar p { color: red; }

75% of the responses expected specificity to override scope (paragraph text is red). And that makes sense to me for several reasons:

• In current tooling, scope proximity doesn't exist (there's no way to express it in the CSS output). Instead the intent of proximity is achieved only through lower-boundaries. If you don't want styles to leak in from an outer scope, you add lower boundaries to that outer scope.
• In this proposal authors can define an outer scope, and decide if it should flow into nested scopes, or have boundaries applied. Component authors could write strongly contained styles with lower boundaries, and also achieve something like the Vue "deep" selectors by having a second scope rule without lower bounds. Rather than making the internal scope powerful so that "no styles get in" we give the external scope boundaries so that "no styles get out".
• If scope proximity overrides specificity, it becomes nearly impossible for authors to penetrate that boundary. The entire goal of this proposal as an alternative to shadow-DOM is that we make the boundaries more flexible, and author-controlled.
• The use-cases I saw where proximity is essential (eg nested light/dark modes) also tended to have the equal specificity, because the goal is to apply variations of the same styles. In that case, we can fall back on proximity without needing it to be powerful.

[astearns]

Post-meeting discussion continued: https://www.w3.org/2021/03/10-css-minutes.html#t07