We reviewed this today in a breakout and while we agree that this use case needs to be solved, we think there might be a way to tweak or to finish implementing some more-general features to solve the use cases, so that we wouldn't need to add features that are specific to web components.

It seems that this is solving two problems:

1. Sharing of styles across shadow roots
2. Defining those styles inline in the containing HTML file

For the first problem, the reasoning listed for why <link> or @import cannot be used for sharing styles across shadow roots is simply that they cause additional network requests. Minimizing network requests also seems to be the core of the reason to use ESM-style CSS imports.

In that case, perhaps the issue can be addressed at the root, by specifying that these requests MUST be deduplicated, either by default (if web compatible) or with a certain flag set. It appears that in most cases UAs deduplicate these anyway, and in cases where they don't, that's not consistent (e.g. @Westbrook shared https://q9yc7v.csb.app/ which causes multiple requests in Chrome but not in Safari), which is encouraging in terms of web compat. Fixing the underlying problem benefits not just web components, but the entire platform at large.

Btw it's incorrect to say that

Inline <style> blocks do not support @import rules

@LeaVerou has personally used inline <style> with @import rules regularly, even in shadow roots (see https://elements.colorjs.io/src/color-picker/). Are you talking about a more specific case they don't work with? E.g. constructible or adopted stylesheets?

To allow these styles to be defined inline, @sheet seems like a better solution. Using <script> for CSS, with specifiers that mimic filenames, seems like a disproportionate level of complexity for the problem being solved, and contorts existing primitives into doing things they were never meant to do. That is, adoptedStylesheets="sheet1, sheet2" seems better than adoptedStylesheets="/invented_filename1.css, /invented_filename2.css". The main drawback listed in the explainer for @sheet is lack of implementations, which seems moot given this is also not implemented?

The idea of ensuring <link> and @import do deduplication is awesome! This should be done, regardless. 👏🏼 👏🏼 👏🏼

While they are doing so, will it be possible to ensure deduplication of that same content when the subsequent request is made in the form of import style from './style.css' with { type: 'css' };? This is likely the secondary request when some styles are handled in HTML and some are handled in JS whether that JS is powering shadow DOM scoped styles or CSS-in-JS solutions.

As part of your breakout, where there any suggestions as to how leveraging these existing APIs in this way could prevent additional network requests at large, or more directly contend with the proposal's approach to inlining the CSS in the initial HTML response?

I think resource fetching ought to be deduplicated between all of <link>, <style src>, CSS @import, and JS import, unless that's not web-compatible for some reason.

We thought the existing @sheet design made sense as the way to inline style in the HTML response without immediately applying it to the page. There was some discussion about whether the platform might be able to avoid adding the adoptedStylesheets attribute and instead somehow use <link rel=stylesheet href="#sheetName">, but none of the obvious ways to do that (e.g. <style id=sheetName some-attribute-that-prevents-immediate-application> or <script type=text/css id=sheetName>) seemed clearly better than adding the attribute to <template>.

A concern about whatever mechanism is used here is that there is an existing behavior of copy-on-write behavior when the same stylesheet is loaded from multiple places. e.g. if I <link> a.css twice, there's one instanace in RAM, but if it's modified via CSSOM, it splits into two instances so page authors can't tell it was shared in the first place.

However, with stylesheets that are adopted via JS API, the same instance is re-used and changes to that instance are reflected in each place they are referenced.

At the least we need to be clear what the expected behavior will be when declaratively adopting a stylesheet. It's also worth thinking about either reconciling the behavior or giving authors explicit mechanisms to opt-in to the behavior they desire.

(As you can tell, this is a real team effort :)

We're happy to see this feature progress. There are a few things that we've identified in the comments above that need to be considered by the working group as you continue to develop the feature. Closing the early review as "satisfied with concerns" to reflect that.

Btw it's incorrect to say that

Inline <style> blocks do not support @import rules

@LeaVerou has personally used inline <style> with @import rules regularly, even in shadow roots (see https://elements.colorjs.io/src/color-picker/). Are you talking about a more specific case they don't work with? E.g. constructible or adopted stylesheets?

The example in the explainer refers to the CSS @import rule, while I think you are referring to JS import? @jyasskin

The example in the explainer refers to the CSS @import rule, while I think you are referring to JS import? @jyasskin

No, I was not referring to a JS import. I was referring to a CSS @import in Shadow DOM, which is what the claim was about. I suspect that whoever thought it was not possible must have tried it with the wrong URL — I do recall some weirdness around how relative URLs are resolved.

FYI all that we've started to look deeper at the @sheet direction suggested by @jyasskin above and have an explainer up here - https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/AtSheet/explainer.md

We'll open a new TAG review for that after we iterate a bit on the open issues and feasibility, but we wanted to share a first look now. Feel free to discuss/provide feedback here, MSEdgeExplainers repo, or the CSSWG issue we opened - https://github.com/w3c/csswg-drafts/issues/11509

In light of some of the discussions around alternatives to this proposal I would like to reopen this for another discussion with TAG along with some specific guidance as to which option we should proceed with.

For some background, given the feedback from the TAG's preference for @sheet over this proposal, I spec'd @sheet (https://github.com/w3c/csswg-drafts/pull/11980) and created a new proposal that allows @sheet to work with inline <style> tags in a Shadow DOM context (https://github.com/whatwg/html/issues/11019). Since then, we've gotten considerable feedback from the community preferring CSS Modules over the new proposals.

Since we've had difficulty finding a single clear path forward we'd appreciate the TAG's advice on which of these potential solutions to prioritize. Asynchronous feedback in this GitHub issue would be great, but given the complexity of the space we think it might also be helpful to discuss on a call with the TAG

Currently @import cannot be used in a constructed stylesheet. Constructed stylesheets are widely used with Shadow DOM. Is there a plan to address this limitation?

It's important to note that constructed stylesheets may be shared across shadowRoots whereas style and link elements cannot. This allows devs to modify a single constructed stylesheet to change styling in any adopting shadowRoot. Not being able to combine this capability with sheets that also use @sheet would force devs tho have to choose between these features rather than easily use them together.

If I may chime in as one of the community members with feedback and the original proposer of Declarative CSS Modules:

I think for much the web components community the fundamental issue with the direction after the initial TAG review was that we don't need a new way of sharing styles across scopes scopes, we need a way of deserializing an HTML payload into the existing way that we already use to share stylesheets: adoptedStyleSheets arrays referencing CSSStyleSheet objects.

I think it would be helpful to judge any proposal against the requirements I laid out in https://github.com/WICG/webcomponents/issues/939 , hopefully clarified a bit here:

1. The ability to serialize constructed stylesheets to HTML on the server, which must only apply where explicitly referenced.
2. The ability to populate a declarative shadow root's adoptedStyleSheets array by referencing serialized constructed stylesheets.
3. To support streaming SSR, the styles must be able to be written with the first scope that uses it and referenced in later scopes, regardless of tree structure or scope nesting.

Or proposals and reviewers could disagree with those requirements, but they seem to be the critical ones among SSR users today, and alternate approaches like @sheet or fragment-referencing <link>s haven't met them yet.

Currently @import cannot be used in a constructed stylesheet. Constructed stylesheets are widely used with Shadow DOM. Is there a plan to address this limitation?

Good point. The @import issue is complex and is being discussed here: https://github.com/WICG/webcomponents/issues/870. Any resolutions in that thread would definitely need to apply here as well.

It's important to note that constructed stylesheets may be shared across shadowRoots whereas style and link elements cannot. This allows devs to modify a single constructed stylesheet to change styling in any adopting shadowRoot.

Yes, this is one of the key requirements of both of my proposals. My alternate proposal handles this as well - it allows for <link> and <style> elements to share and underlying sheet with shadow roots.

Not being able to combine this capability with sheets that also use @sheet would force devs tho have to choose between these features rather than easily use them together.

This is a great point, and I have already thought about this - in order for @sheet to work with declarative a adoptedstylesheets attribute, we'd need a new sheet attribute on <template>, similar to this proposal for <link> tags: https://github.com/whatwg/html/issues/11022. Imperative shadow DOM can handle @sheet support by using braces with the from syntax, e.g. import {foo} from bar.css with { type: "css" }; would import the @sheet named "foo".

As an author of two different server renderers for web components, I want to chime in and say that I agree with @justinfagnani completely on his concerns and the outline of the requirements.

Summarizing some of the discussion on this topic I have seen, I would like to emphasize that to me there seems to be a lot of similarities in declaratively sharing a <style> element (and/or an @sheet in it) into a shadow tree by way of a <link> element and by way of an adopted stylesheet.

<style id="shared_styles">
  p {
    color: blue;
  }
</style>
<element-with-link>
  <template shadowrootmode="open">
    <link rel="stylesheet" href="#shared_styles">
    <p>what color am I?</p>
  </template>
</element-with-link>
<my-element-with-adopted-style>
  <template shadowrootmode="open" shadowRootAdoptedStylesheets="shared_styles">
    <p>what color am I?</p>
  </template>
</my-element-with-adopted-style>

Both seem to require the same answers to the same enabling decisions:

• specify a resolver algorithm that uniquely identifies which <style> element is being referenced (and distinguish between <style> elements with duplicate identifiers)
• decide whether the <style> element should be shared or cloned (shared seems preferable)
• decide whether the <style> element should be only in the light DOM or can also be in a shadow DOM
• decide the exact referencing syntax: for example "#shared_styles" (like the SVG <use href= "#shared"> analogy) or other syntax like "global:shared_styles"
• decide whether the <style id> attribute can be used to refer to the <style> element from the shadow DOM, or whether some other mechanism is needed
• decide how to reference one or more @sheets in the <style> element and how to reference only those CSS rules not in an @sheet

Given these same enabling decisions, perhaps enabling both is not significantly different or more complex than enabling only one.

The key differences I see are for the user of the <link> element or the adoptedStyleSheet attribute:

• The <link> element and adoptedStyleSheet attribute would have different CSS cascade consequences, with <link> being somewhat more flexible.
• The <link> element could also be used without a declarative shadow DOM.
• An adoptedStyleSheet attribute on a declarative shadow tree <template> is not polyfillable because the <template> is removed at parse time.

Perhaps there are other significant or compelling differences, though I for one don't see streaming SSR (HTTP Transfer-Encoding: chunked) alone as one of them, but rather as a use case feeding into the decision points for either.

One hard requirement I have is that there MUST be a way for declarative styles added to declarative Shadow DOM to be present in the adoptedStyleSheets array of the shadow root and the style sheet instance MUST be the same across all shadow roots that reference the same declared styles.

This is critical for libraries, frameworks, hydration, interoperability, etc.

The runtime representation must be consistent regardless of whether things were set up declaratively or imperatively. We already have a proven model for sharing styles imperatively, which is in broad use. We just need the declarative equivalent.

Another hard requirement I have is that declarative shadow root adopted styles MUST be able to reference any declarative styles that have previously been parsed, regardless of their position in the node hierarchy (previous sibling, ancestor, shadow root of sibling/ancestor, etc.).

This is critical for server rendering scenarios.

I care much less about the syntax, but if these semantics are messed up...

Apologies for the ignorant question, but what goes wrong if a declarative shadow root can "import" styles from anywhere else in the document (including ones serialized inside another mode=open shadow root), but those styles don't wind up in the adoptedStyleSheets array? Are folks modifying these sheets, and expecting those modifications to change everywhere that refers to them? Are folks reading sheets out of adoptedStyleSheets and expecting that to be complete? I expect @justinfagnani and @EisenbergEffect are correct that this is critical; I'd just like to understand better what's relying on it.

what goes wrong if... those styles don't wind up in the adoptedStyleSheets array?

Typically, DSD is used to mirror and fully emulate (often via server rendering + hydration) an element that can otherwise be imperatively rendered. If adoptedStyleSheets isn't used, presumably an element(s) in the shadowRoot would be? If so, this is semantically different from the imperative version that would almost certainly use adoptedStyleSheets. That difference can lead to subtle issues in both performance and correctness. A style/link element is heavier weight than a stylesheet, and the presence of an unexpected element can influence the styling of other elements in the tree. In the case of a link element it would have to 100% guarantee not to produce a FOUC. Unfortunately, documentation and spec behavior for FOUC is extremely confusing.

Are folks modifying these sheets, and expecting those modifications to change everywhere that refers to them?

In some advanced cases, yes. And again, if the platform provides some alternate mechanism for DSD, these use cases just become incompatible.

Are folks reading sheets out of adoptedStyleSheets and expecting that to be complete?

Yes. The styling API for Shadow DOM has not evolved to meet user needs, and this leads to use cases that involve relying on and manipulating adoptedStyleSheets.

In short, adoptedStyleSheets is by far the most common way to apply styles to Shadow DOM. I really haven't seen anyone use or prefer style/link since the addition of adoptedStyleSheets except since the introduction of DSD. And that's led directly to this issue...

I'm posting the following on behalf of the TAG. Authorship credit for the comment largely goes to @jyasskin who is on vacation for the next week and a half but who drafted the bulk of it prior to leaving.

Thanks everyone for looking into the @sheet design space and then bringing this back to us when it didn't work out. We agree that @justinfagnani's constraints in https://github.com/w3ctag/design-reviews/issues/1000#issuecomment-3076124488 need to be met by any reasonable solution and that it's important to solve this, even if we have to accept a design that's less theoretically pure.

We have a bunch of thoughts and questions about the details. We suspect specifiers and integration with the module map is going in the right direction, but we want to check that they integrate well and that you've fully explored a couple other options.

On @sorvell's point that "@import cannot be used in a constructed stylesheet.", we agree that's a problem, but we think it can be solved independently of this design, so we won't consider it further here.

On the explainer

It would be good for the explainer to show the HTML for the sort of component nesting that requires the proposed solution. We're working from @jyasskin's example in https://github.com/w3c/csswg-drafts/issues/11509#issuecomment-2651701885, but there should be a canonical example in the explainer.

Showing specifiers like /foo.html makes it look like a document is trying to claim parts of the URL space, but we don't think that's what you're actually proposing. Please avoid showing specifiers like this, or if it's the intention to allow these to behave like URLs, make that clear and detail how it's expected to work.

Details to flesh out

Please describe how this integrates with the module map and with importmaps in more detail. We assume it'll be possible to assign specifiers with either <style type="css-module" specifier="bar"> or <script type="importmap">{"imports": {"bar": "./foo.css"}}</script> and use them with either adoptedstylesheets=bar or import styles from 'bar' with { type: 'css' };, but you should say it explicitly. Is specifier truly just a shorthand for an adjacent importmap, or does it do something more?

Was it ever intentional that <script type="importmap"> works inside a shadow root? It'd be good to check with that feature's designers (e.g. @domenic) to ensure that encouraging its use there won't break any assumptions or encourage any footguns.

Alternatives to consider

It sounds like the fundamental difference between <link rel=stylesheet> and adoptedstylesheets is whether the sheets are applied by value or by reference. (And when they're applied by reference they appear in the adopedStylesheets JS list.) Please look for ways to make the syntaxes more similar, for example by giving <link rel="adopt stylesheet"> the by-reference semantics. This may need to define a way for <link> elements to refer to into the module map instead of just to URLs, which might or might not be the href attribute.

As described in https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/ShadowDOM/explainer.md#scoping and in @justinfagnani's requirements, it's important to be able to name things across shadow boundaries. The easiest way to do that is to use a global mapping like the module map, but as we saw with the custom element registry, we often find a later need to scope that global object. What if, instead, we defined a way to name style elements or @sheets across shadow boundaries? open shadow roots could be pierced explicitly from the outside, perhaps by using a #id-of-host:~:within-shadow=id-inside-shadow/id-inside-that-host. (/ might not be the best way to traverse multiple levels, and :~: is from text fragments.) closed shadow roots need to explicitly export the relevant elements, and phase 1 of referenceTarget probably isn't flexible enough. It might be reasonable just to postpone handling closed shadow roots. This might turn out to be too complex, but you ought to explore the possibility.

Because the current specifier attribute does expose its element across shadow boundaries, it might be better to name it in a way that flags this behavior. Perhaps exportspecifier.

Changes you should probably make

You have adoptedstylesheets taking a comma-separated list of specifiers, but we have a design principle that it should be space-separated.

Thank you for the feedback! I recently updated the explainer to respond to these questions. I will link to individual sections as responses to help clarify things.

It would be good for the explainer to show the HTML for the sort of component nesting that requires the proposed solution.

The explainer has been updated with a Streaming SSR example of this scenario and how this solution addresses it.

Please avoid showing specifiers like this, or if it's the intention to allow these to behave like URLs, make that clear and detail how it's expected to work.

This section of the explainer has been updated with a step-by-step workflow of how we expect these specifiers to interact with the module map.

Was it ever intentional that <script type="importmap"> works inside a shadow root?

Good question. I will follow up with @domenic offline to resolve this. In the mean time, I'll add this to the explainer as an open issue.

Please look for ways to make the syntaxes more similar, for example by giving <link rel="adopt stylesheet"> the by-reference semantics

This is a great suggestion, and allows for more flexibility with this proposal (@sheet, media queries, etc.). The specifics should be discussed with WHATWG stakeholders. In the mean time, I have added this to the explainer here.

What if, instead, we defined a way to name style elements or @sheets across shadow boundaries?

As mentioned in the updated explainer, @sheet alone won't be a replacement for this feature due to the fact that there's no mechanism to include an @sheet with inline styles - they must be in an external file. Inline styles are a key part of the Streaming SSR scenario that this proposal allows. I will note that using a link tag to adopt styles will allow for clean integration with @sheet (without requiring names to cross shadow boundaries).

Because the current specifier attribute does expose its element across shadow boundaries, it might be better to name it in a way that flags this behavior. Perhaps exportspecifier.

Great idea, this has been incorporated into the explainer.

You have adoptedstylesheets taking a comma-separated list of specifiers, but we have a design principle that it should be space-separated.

The explainer has been updated accordingly.

Please take a look at the the updated explainer and let me know if there are any more issues that should be addressed.