Theming options for shadow roots

[justinfagnani]

I just realized we didn't have an issue for theming after ::theme was removed from the Shadow Parts proposal. I'm not sure if this is tracked elsewhere or not.

Many, many, web components authors and users need a way to do deep cross-shadow root styling. Shadow parts get us part way there, but require extensive forwarding to enable application-wide or sub-tree theming. ::theme might solve a lot of cases, but the concept needs to be refined to find an acceptable shape. There are other musing around about more open shadow roots.

We've seen a few different userland approaches to theming, often built around injecting styles from a global registry into shadow roots.

I think there are a few variations on the problems to target, and obvious a lot of potential solutions. Hopefully we can gather both here and tease out some commonalities.

[rniwa]

What are examples of user land solutions? We need to study how various libraries & frameworks are tackling this problem & list of concrete use cases so that we can evaluate each proposal properly.

[justinfagnani]

This is the most developed one that I know of: https://github.com/vaadin/vaadin-themable-mixin (cc @web-padawan)

You could basically consider the @apply polyfill an example of userland theming. Details of implementation somewhere deep in here: https://github.com/webcomponents/polyfills/tree/master/packages/shadycss

And @aomarks has been looking at a new system inspired by Vaadin's themable work, @apply, the ::theme idea and CSS shadow parts.

[Jamesernator]

One of the hazards with ::theme is that it might capture names from shadow roots unintentionally rather than opt-in.

I feel like most of the objections with using it for theming could be solved by providing a mechanism to use imported names to use for styling (akin to my previous suggestion on lexical names).

e.g. Consider this example that provides deep theming for syntax highlighting:

/* styles.css */
@part $var-token {
  deep: true;
}

/* code-/register.js */
import { var, keyword } from './styles.css';

/// ...
  for (const token of tokens) {
    if (token.type === 'var') {
      const varElement = createVarElement(token);
      varElement.parts.add(var);
    } else if (token.type === 'keyword') {
      const keywordElement = createKeywordElement(token);
      keywordElement.parts.add(keyword);
    }
    // ...
  }

/// ...

<!doctype-html>

<style>
  @import "/components/code-/styles.css" {
    /* Import lexically scoped part name */
    $var;
    $keyword;
  };

  /* Syntax highlighting theme */

  /*
    * ::theme would be deep but only work on lexically exported part names
    * ::part would operate on local tree as per usual and doesn't pierce shadow roots
    */
  ::theme($var) {
    color: yellow;
  }

  ::theme($keyword) {
    color: green;
  }
</style>

<!-- This shadow root is loaded from the article file -->
<blog-post src="./how-to-program.html">
  <#shadow-root>
    Hello this is hello world!
    <code- lang="js">
      console.log("Hello world!");
    </code->
  </#shadow-root>
</blog-post>

[justinfagnani]

I think lexical names, while useful (the linked proposal is from me), is quite a large lift for this feature. We have existing cross-scope features that rely on string names, like CSS variables. It seems to me like we can do something opt-in with names and support lexical names if and when that ability comes to CSS.

::theme previously had been proposed as a new selector that matched elements with part attributes. ::theme was somewhat opt-in in that an element ahd to mark some of its shadow elements as parts for them to be themable, but in the sense that a part attribute didn't necessary opt a grandparent scope into having a styleable part, ::theme wasn't opt-in.

One change discussed was just using a separate attribute, like theme. The idea being that while part shouldn't opt-in to deep theming because it's main intent is to expose a part to the direct containing scope, a theme attribute could be an explicit opt-in to that behavior. Of course the ancestor scopes still haven't opted into deep styling, so the questions become about that. Can theming be opt-out for containing scopes? Shadow roots with themable parts specify those, and they're by default themable from anywhere above in the tree, but containing scopes could have a way to block theming - maybe an option to attachShadow?

[Jamesernator]

I think lexical names, while useful (the linked proposal is from me), is quite a large lift for this feature.

I don't know how browser stylesheet internals work but it should be no harder than @namespace even including importing them.

The implementation would basically be treat @import './foo.js' { $bar; } as "replace all $bar tokens with https://resolved.url/path/to/foo.js#bar".

It'd be pseudo like if it was written as:

::theme(https://resolved.url/path/to/foo.js#bar) {
  color: blue;
}

element.parts.add(new URL('https://resolved.url/path/to/foo.js#bar'));

This would just then follow the processing model of ::theme(simple-name) to find matching elements, as has been proposed in the past.

[web-padawan]

Regarding the user land solutions: at Vaadin we do inject styles to shadow roots:

• using ThemableMixin with Polymer,
• using ThemableElement with LitElement.

While we use part attribute internally, and have an agreement that parts are considered public API following semver, using ::part only isn't enough for cases like "style all the buttons".

Another example of a user-land solution that is currently a prototype is Stylable util:

Let components pick up matching style sheets from the global scope (document, for theming) and from the scope they are contained in (their parent shadow root, for styling).

The matching is done using the standard media query feature. Using a custom media query makes the contained rules (either a full or partial style sheet) inert from the document so that the style rules do not end up matching unintended elements.

See also full documentation here.

Of course this isn't something that we'd like to use in production today and we agree that (ab)using media queries for styling Shadow DOM is arguable and might affect performance.

@jouni would you like to share the slides from your recent presentation on this BTW?

[jouni]

Here’s the presentation I created to illustrate my frustrations with our existing theming solution (ThemableMixin) and how media queries could be used as a similar workaround but with a little nicer developer/designer experience: https://docs.google.com/presentation/d/1on1vav0grmtPiOsGfx0qbTIJ8ryiMMTJxOyx-jOmBhQ/edit#slide=id.g6b7ea3c84b_0_103

[jouni]

I have some concerns regarding ::theme.

How is it supposed to work with host elements? As an example, how should <vaadin-button> allow itself to be themed? Does it need to add a part attribute on itself in connectedCallback if not already specified by the user? How else could ::theme() target all <vaadin-button> elements in all style scopes?

If a part attribute is required on the host, then I suppose it’s not possible to style all native elements across all style scopes without them having an explicit part attribute. I suppose that’s the expected behavior, that as a component author I can guarantee that no one can affect the styles of my component unintentionally.

I haven’t come to a conclusion with my thoughts whether themable elements should always be exposed in the light DOM so they would participate in global styling without any additional platform capabilities. Somehow it feels like shadow DOM should reserved for internal implementation details, and the component author doesn’t want you to mess with those. ::part is an escape hatch of sorts, and that might be sufficient if there’s a relatively easy way to attach/adopt style sheets to any shadow root.

[rniwa]

Using @ rules is an interesting idea. The one problem I see with that approach is that users of components can defile an arbitrary list of selectors. How does component define which elements' styles can be overridden, and which one can't be?

Another complain / concern I have with ::part and the old ::theme is that there isn't a convenient way to specify a set of properties which are allowed to be changed. It seems like a pretty big oversight to me.

[emilio]

Another complain / concern I have with ::part and the old ::theme is that there isn't a convenient way to specify a set of properties which are allowed to be changed. It seems like a pretty big oversight to me.

I think the way importance was defined in Shadow DOM (so that the rules in the shadow root always win) were intended to address such a thing (at least for ::part, not familiar with the old ::theme spec).

So you could use !important to avoid the outside overriding specific properties, or all: revert !important or such to avoid overriding any properties, and explicitly opt-in after or such.

[paales]

::theme() modifications

I've got a concern with the 'old' ::theme proposal why it doesn't work:

<html><body>
<style>
  ::theme(my-button) {
    color:hotpink;
  }
  ::theme(my-component1) {
    background: red;
  }
  ::theme(my-component2) {
    background: blue;
  }
  ::theme(my-component-part) {
    background: green;
  }
</style>
<my-button part="my-button">text</my-button> <!-- color: inherit ❌ -->
<my-component1 part="my-component1"> <!-- background: inherit ❌ -->
  #shadow-root
    <div part="my-component-part"></div> <!-- background: green ✅ -->
    <my-button part="my-button">text</my-button> <!-- color: hotpink ✅ -->
    <my-component2 part="my-component2"> <!-- background: blue ✅ -->
      #shadow-root
        <div part="my-component-part"></div> <!-- color: green ✅ -->
        <my-button part="my-button">text</my-button> <!-- color: hotpink ✅ -->
    </my-component2>
</my-component1>
</body></html>

But how can we handle those first two crosses? The idea behind ::theme is that a frontend developer shouldn't care about the rootNode in which the component is in, right?

In the previous draft I believe it was as follows:

• ::part selectors pierce only 1 shadow boundary.
• ::theme selectors pierce 1 or more shadow boundaries.

I would propose a change:

• ::theme selectors pierce 0 or more shadow boundaries.

This would allow us to fix the above issue.

Statefull components

How should we handle internal state of a component? How can se select every my-button[disabled] and theme that? Should I now also publish all the state attribute of the components as parts with my own naming convention? 🤢

If we allow to use selectors behind the ::theme() bit, this would solve the issue:

::theme(my-button)[disabled] {}

This isn't an issue with the ::part specification because that only pierces one boundary from the outside so you can always select the element directly.

Arguments agains the @media my-component

It looks like a hack to 'select' elements though a shadow root? But media queries aren't selectors, they allow for selecting based on the environment and a component isn't an environment variable. So I think we should stay with a selector to select the webcomponent/part. Does your proposal also allow for div? How does a component 'whitelist' it's self? How would a component expose certain parts of their inners?

Style scoping

How do we create a different theme area? For example: the content of the page is white and the footer is black, how can we scope the themes, that also work acros shadow boundaries?

dark-theme::theme(my-button) { bla:bla; }

The bit is the part of on the left? This can't be specified globally, because it needs to be present in every shadowRoot for this to work (think nested themes). This would need a custom webcomponent to achieve this.

The idea is that we allow for reading CSS variables in the selector. Those cascade down so we can achieve nested themes. I believe there currently aren't any boolean css properties, but it can still do a string match?

::theme(my-button)::var(--dark-theme) { bla:bla; }

[web-padawan]

If we allow to use selectors behind the ::theme() bit, this would solve the issue:

That should be covered by custom :state pseudo-class, right? See #738

[jouni]

It looks like a hack to 'select' elements though a shadow root?

Yes, it is. I was mainly looking at a workaround with a syntax that browsers currently parse as valid CSS so that the styles can be accessed through the DOM API, and not resort to parsing strings with regular expressions.

Another alternative I played with was @namespace. You can abuse that similarly, that selectors are parsed by the browser but not applied to elements automatically. Then you can traverse the style sheets through the DOM API and pick up the styles you want to apply to your component.

---

Using @ rules is an interesting idea. The one problem I see with that approach is that users of components can defile an arbitrary list of selectors. How does component define which elements' styles can be overridden, and which one can't be?

Yeah, that’s a problem for sure, and probably a big enough to discard the idea of using @-rules. I assume it’s a bad idea to only parse ::part and :state selectors inside such @-rules? It’s kinda like ::shadow and /deep/ all over again. For example:

@shadow my-component {
  ::part(foobar) {
    ...
  }
}