Dark mode does not auto switch

[andinus]

Describe the bug When visiting docs.raku.org, if you change the dark mode preference, docs.raku.org does not auto switch.

To Reproduce Steps to reproduce the behavior:

1. Go to docs.raku.org, currently dark mode enabled
2. Change preference from dark to light
3. docs.raku.org is still in dark mode

Expected behavior The website should switch from dark to light mode, it stays dark mode even after a refresh.

Screenshots I'm attaching a screen recording:

https://github.com/Raku/doc-website/assets/62012039/cc5431eb-4ad4-45ad-8837-ca6a99b82d3d

Desktop (please complete the following information):

• OS: macOS
• Browser Safari, Firefox

[finanalyst]

@andinus From the screen recording I see that you are using a browser based tool to switch from light to dark mode, rather than the toggle at the bottom of each page, which uses in-site javascript to change between themes. This issue is reminiscent of issue #252. It was closed when the issue disappeared, though it was never resolved why. There seems to be a way to synchronise the switching of themes externally, as you have done, with internally. I don't know why or how to resolve this. Any suggestions?

[patrickbkr]

It's not a browser based tool, but the MacOS theme switcher that switches the theme of the entire OS. Similar tools exist on Windows, Gnome and KDE. Browsers can pick that up. I haven't read through it fully, but https://css-tricks.com/a-complete-guide-to-dark-mode-on-the-web/ seems like a good overview. The prefers-color-scheme media query seems to be the central bit that enables this.

The Dark Reader issue (#252) is different in that Dark Reader is a browser addin that modifies websites. I personally rely on the dark theme websites provide and only use Dark Reader for the others that don't have a dark theme.

GitHub is an interesting example. They let you chose a specific theme, but also have a "sync with system" option. (See Settings -> Appearance)

[andinus]

Yes, the tool modifies prefers-color-scheme. Something like this should work:

:root {
    --bg-main: #ffffff;
    --bg-dim: #f8f8f8;
    --bg-alt: #f0f0f0;

    /* ... */
}
@media (prefers-color-scheme: dark) {
    :root {
        --bg-main: #000000;
        --bg-dim: #100f10;
        --bg-alt: #191a1b;

        /* ... */
    }
}
/* here we can use these variables */

However, it's not a bad idea to allow the user to override the theme. Maybe we can have an event when browser's prefers-color-scheme changes, and with 3 modes: "automatic" (based on browser's theme), "light" & "dark".

[finanalyst]

@andinus @patrickbkr I appreciate the feedback. I also looked to see what Bulma does natively. I think this issue has highlighted a design flaw that I was vaguely aware of before, but now is a bit clearer.

The Bulma framework has an extensive section on themes and I'm pretty certain, it will take care of the different ways to change themes.

To be frank, when I adapted the new website design to run with Collection, instead of Documentable, I cut and pasted as much of the basic design as possible, which included an ad-hoc theme changer. I have extended this to other plugins (tablemanager, secondaries, announcements, option-search &c). IMHO its a bit of a hack.

My thought is rather than adding to the hacks to get this issue corrected, and even to allow for more than two themes, the approach needs to change. The basic SCSS variables need to be set in one place, and to be available to all plugins, in some way. Then theme changes should be done by a Bulma component.

This will take some time ... (My current priority is writing a RakuAST-RakuDoc renderer to replace Raku-Pod-Render, followed by a CMS to replace Collection).

If someone can suggest some patches that would quickly change things, I'd appreciate it.

[finanalyst]

@coke @patrickbkr @dontlaugh To get consistent themes will require some extensive refactoring. Before I start working on this, here is the goal, and the steps needed to achieve it. Please let me know as soon as possible if you have significant concerns in order to prevent time being wasted. I propose to manage the refactoring using the docs-dev branch.

Goal:

1. Define 'light' and 'dark' themes in a way that can be picked up by all components of the website, and allow for additional themes in the future, such a 'pastel', 'high-contrast', or themes better suited for smart phones, eg. larger text font sizes; and that all plugins must conform to a single theming mechanism.
2. Themes can be developed and tested independently of knowing anything about the detail of any other plugin, or how the HTML of the pages are built. In this way, a new theme can be suggested by any user.
3. The theme can be changed using an 'in browser' selector that is consistent with OS / browser selection tools for which there is a standardised API.
4. Change the current 'in browser' selector on our site from a toggle button on the bottom of the webpage, to a drop-down selector from 'More' in the navigation bar.

   The current theme selector is a toggle button at the very bottom of the webpage, and it is inconvenient because in order to change the theme, the user has to scroll to the bottom of the page, where it is not easily noticed.

To achieve this goal, the following refactoring needs to happen:

• The Bulma framework used by the whole website has an extensive mechanism for defining themes, which appears to be consistent with external browser and OS tools. Thus goal 3 above will be met by using the Bulma mechanism consistently.
  • Bulma uses SCSS variables to define font sizes and colours in each instance of a named div, and for each theme to define those variables appropriately for the theme. This approach needs to be implemented for the Website
• The Website is built using 'plugins' to handle different functionalities, such as the search, ToC, tables, and each plugin has its own SCSS. The underlying SCSS variables are hard copied to each plugin directory. There is no way to define variables in one place, and for the new variable values to be effective everywhere.
• Currently, all the CSS for each plugin is generated from SCSS before Build time, and then copied to the assets/ directory for the HTML of the Website.
• The plan is to generate the CSS from the SCSS for each plugin at build time using a single source of SCSS variables.
• This can be done in small steps because each plugin has its own config file that defines the CSS files to be transferred, and there is another plugin that gathers the CSS using the config entries.
  • The plan will be to create another plugin that gathers SCSS files from a new config key in each plugin, generate themed CSS, use a single source for variables.
  • Once the SCSS plugin starts working as expected, the CSS plugin can be disabled and the SCSS can be enabled.

In addition, all the CSS files can be treated as "artifacts" for the containerisation process, and so will not need to be regenerated at each BUILD session.