[css-cascade][css-scoping] Allow layers to use different names in different contexts

[knowler]

Background

There’s some desire to write “isomorphic stylesheets” that would work for both a document and in shadow roots (WICG/webcomponents#909, WICG/webcomponents#986). This can be problematic, especially with layers since they are often context-specific conventions. Requiring a consumer of a web component to use the same layer names is problematic (it makes the component hard to use), just as expecting the author of a web component to know what layers a consumer is using.

This proposal isn’t focused on how external styles can access a shadow root, but rather seeks to improve the adaptability of layering when styles are used in different contexts.

Syntax

The proposed syntax would extend the existing layering syntax:

/* As a layer statement rule (useful when sharing entire stylesheets) */
@layer
  defaults as (reset in one-element, base in another-element),
  components as (elements in one-element, blocks in another-element);

/* As a layer block rule (useful when applying a subset of styles to another context) */
@layer defaults as (reset in one-element, base in another-element) {

}

The syntax structure would be:

@layer <layer-name> as (<inner-context-layer-name> in <selector-with-inner-context>)

The selector would effectively match with :host(), e.g. if :host(another-element) use base as the layer name.

If no layer name for a specific inner context is given, the original layer name would be used.

If a context has already established its layering order, when subsequent layer statement rules appear with contextual layer names, those layer names become associated with the corresponding names in the existing order (they do not modify the order).

Use cases

Ideally, this proposal would be complementary to an happy-path way to apply external styles to a shadow root either as a whole or in part. Even without that happy-path, I do believe it can be useful for web component authors who already are supporting ways to inject external styles into their shadow roots.

[mayank99]

It might be more useful to allow a generic way to create an alias of a layer name. It doesn't necessarily need to be tied to contexts.

/* creates an alias in the current context */
@layer defaults as base;

This would be useful even without shadow DOM, especially when working with third-party stylesheets that have their own layer names. For example, tailwindcss v4 preconfigures base and utilities as layer names and you might want to merge those layers with your own layers (which probably have different names).

This same concept can be applied to shadow contexts by nesting the layer alias statement inside a selector (making the in syntax redundant). This would play nicely with a mechanism for adopting host stylesheets.

/* creates aliases in shadow context (when adopted by the shadow root) */
:host(one-element) {
  @layer defaults as reset;
}
:host(another-element) {
  @layer defaults as base;
}

I'm not sure if this fits into your proposal or should be its own separate thing, but I just wanted to mention it while it's still fresh in my mind.