Docs Dark/Light Theme #5

jorenbroekema · 2021-08-09T12:30:34Z

jorenbroekema
Aug 9, 2021

Docs Dark/Light Theme

It would be great if the BKL docs section, whether it uses MDJS or MDX or other tech, has by default a dark theme toggler.
What this will allow is that Component/DS authors can create things that have built-in dark-mode support, and without having to think about app/docs structure, they get working demos that can showcase this dark-mode integration. Dark mode is becoming the new responsive in terms of "no longer nice-to-have, but a fundamental requirement", and some developers even argue to build dark-mode-first, light-mode-later, when in a hurry.

In order to provide a working theme switch out of the box, we should align on some conventions, so this discussion is essentially a proposal for that, you can see it working https://backlight.dev/edit/5vtJtbY04aoD1dGKcsu1 here.

Global Theme Attribute

To tell the page that we are in "dark" or in "light" mode, a "theme" attribute is used on the html element:

<html theme="dark">
  <head></head>
  <body></body>
</html>

This is the attribute that theme controls will interact with.

Theme Togglers

A custom-element that changes the theme between "light" and "dark". There's a few implementation details that are important to note:

The theme toggler, when interacted with, needs to store the user preference to Local Storage, so that it is saved for consecutive usage
If no user preference in Local Storage, it makes sense to use the Operating System default (Windows/Mac both have dark-mode support), using CSS media prefers-color-scheme.
If the user changes OS theme, it is a good assumption that we should change the theme on the page too, and store
There could be multiple theme togglers on the page. Therefore, it makes sense that every theme toggler is connected to the same MutationObserver that fires when the theme attribute changes, to ensure every toggler stays in sync.

The idea is that we bring such a toggle into BKL docs, by default, so users have that out of the box with 0 effort.

Components Using ShadowDOM

It is a bit awkward to have components with fully encapsulated styles using ShadowDOM to respond to the global theme which is outside of this encapsulation.

For example, this does not work, by design:

html[theme="dark"] :host {
  color: white;
}

but this does:

:host([theme="dark"]) {
  color: white;
}

There's a pretty straightforward, VanillaJS way to have your class-based components always sync their internal theme attribute to the global theme attribute, and it could be adapted to functional components too. It is essentially an interface implemented on every component with dark-mode-support that handles this:

const themeObserver = new MutationObserver((list) => {
  registeredComponents.forEach((comp) => {
    comp.theme = document.documentElement.getAttribute('theme');
  });
});
themeObserver.observe(document.documentElement, {
  attributes: true,
  attributeFilter: ['theme'],
});

const registeredComponents = [];

export const ThemeMixin = (superclass) =>
  class extends superclass {
    get theme() {
      return this.getAttribute('theme');
    }
    
    set theme(val) {
      this.setAttribute('theme', val);
    }

    constructor() {
      super();
      registeredComponents.push(this);
      this.theme = document.documentElement.getAttribute('theme');
    }
  };

Again, this can be seen in action here: https://backlight.dev/edit/5vtJtbY04aoD1dGKcsu1 , go to "Infrastructure -> Themes" to see the src code.

bashmish · 2021-08-09T13:35:10Z

bashmish
Aug 9, 2021

I think ideally the theme toggle should be part of the client (Backlight shell in this case, like some other tools) and also ideally it should set prefers-color-scheme for the iframe context. The latter is not possible AFAIK, but the first should be so that every starter doesn't need to include any theme toggle components in stories (yes, also them) or docs and maintain them.

Since prefers-color-scheme can't be changed in JS, we indeed need our own standardised API. And all starters need to adopt it which is annoying since we'll need to do some extra wiring depending on the DS type. Your idea with the <html theme> attribute seems like a good starting point. themeObserver and ThemeMixin and any other reusable pieces can become a lib.

1 reply

jorenbroekema Aug 9, 2021
Author

Yep, I think we pretty much align on the overall idea. I don't really have a strong opinion on where the toggle should be :). I'm actually thinking of making both the ThemeMixin and the ThemeToggler open-source on my own namespace including tests, I developed 95% of it in my spare time and 5% was just fixing some stuff that showed up while using inside BKL. I also have the non-lit, vanilla HTMLElement versions of them locally.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs Dark/Light Theme #5

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 1 comment 1 reply

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

Select a reply

Docs Dark/Light Theme #5

jorenbroekema Aug 9, 2021

Docs Dark/Light Theme

Global Theme Attribute

Theme Togglers

Components Using ShadowDOM

Replies: 1 comment · 1 reply

bashmish Aug 9, 2021

jorenbroekema Aug 9, 2021 Author

jorenbroekema
Aug 9, 2021

Replies: 1 comment 1 reply

bashmish
Aug 9, 2021

jorenbroekema Aug 9, 2021
Author