Light mode for Bevy website -- draft PR

[lynnpepin]

Background: Light mode as an accessibility necessity.

Hi! I'm an enthusiastic new user to this Bevy, but I've hit a small roadblock: The docs are light-on-dark! (I.e. dark mode).

I have astigmatism, which is making it difficult to read and use the docs (e.g. https://bevyengine.org/learn/quick-start/introduction/ ) because of its dark theme. Here's a relevant StackOverflow post regarding the merits of dark vs light theme.

Readers don't have good options to mitigate this. Readers can use this client-side with a "Reader" tool, but not all browsers have this. Readers can also use a theming extension, but these are a security concern for requiring permissions on all websites, and not all browsers have an extension system.

Referenced in issue 974 and duplicates, I hope adding light mode can bring more birds into the Bevy :)

New work: Light mode theme

So, I modified the Bevy website theme (rather extensively), with two primary changes:

• Start using @media (prefers-color-scheme: ...) such that the theme will respond to system light/dark mode settings, and
• Replace SCSS variables (which are baked ahead of time) with CSS variables (which can respond to @media (prefers-color-scheme.
• A number of other small implementation details, using CSS filter and backgrounds creatively, with the intention of not requiring maintainers to double their work (e.g. when creating header images.)

One outstanding piece of work for lightmode is rewriting the syntax-highlighting. I didn't touch this, instead opting to keep all the code as dark-on-light. This might be worth another PR down the line.

I'm hosting my fork of the themes on my site, at bevydocs.lynndotpy.dev/. Turn your system to light mode and visit the site to see the new theme!

Outstanding task: Theme toggler

There is one change I have not made yet, but was requested before merging: Putting light mode behind a toggle. This makes an outstanding task, which will have two parts:

• Create the toggle code (~20% of the work)
• Retrofit it onto the CSS (~80% of the work)

Regarding implementation, this will be a bit difficult because, as it turns out, JavaScript can't toggle prefers-color-scheme on the webpage. (Woops! Would save time if I thought ahead to check this.)

The intention is for the toggler to mostly follow the behavior of the docs.rs theme toggler, with the exception of defaulting to dark-mode. (Docs.rs defaults to system preference.)

For branding / consistency, the Bevy instead would like dark mode to be the default. In order to allow the Bevy to enjoy full functionality even without Javascript, that means an implementation detail: The true default will still be "follow system preferences", but that will be overwritten by Javascript on load, which will set it to dark mode (unless the user has already set a preference).

Functionally, most users in the Bevy will see this as dark-mode-by-default.

So, the toggle will need these specifications:

• A new UI element to allow users to select between "dark", "light", and "system preferences" themes.
• When Javascript is not enabled, this should follow system-preferences.
• When Javascript is enabled, this should be "dark" mode by default.
• When Javascript is enabled, this should store and load the user preference from localStorage.
• When Javascript is enabled, this should modify the CSS used, to apply dark/light mode.
  • The dark/light mode selected by Javascript should be completely identical to the one selected by the system theme.
    This sounds obvious, but it is possible to make a mistake with this in implementation.

I've done no work on the toggler yet, so, there will be a lot of that before this PR.

Screenshots and preview:

I host a preview of this lightmode at bevydocs.lynndotpy.dev! Please check it out, please critique vociferously :)

[ariofrio]

This looks great! Honestly, it might personally become my preferred way of viewing the Bevy website.

Some design nitpicks:

I think the dark gray borders and the gray item backgrounds in light mode should be lighter. Compare the contrast:

---

And I'm sure you've noticed this already, the Assets item titles should have a white text, or a white (translucent) background. I would also change the borders and backgrounds the same way as above. Compare:

[LiamGallagher737]

Rather than inverting the dark mode logo could you use the light logo?

[lynnpepin]

Hi all-- sorry for being so late to come back to this. While the style update is mostly done, I haven't been able to make progress on the three-state toggle. If someone else wants to take that on, I'd appreciate it.

This looks great! Honestly, it might personally become my preferred way of viewing the Bevy website.

Some design nitpicks:

I think the dark gray borders and the gray item backgrounds in light mode should be lighter. Compare the contrast:

And I'm sure you've noticed this already, the Assets item titles should have a white text, or a white (translucent) background. I would also change the borders and backgrounds the same way as above. Compare:

Thank you for the feedback! Good idea regarding the borders-- they should have less contrast.

Rather than inverting the dark mode logo could you use the light logo?

I originally used the light logo, controlled with prefers-color-scheme, but it ended up more consistent to do an invert IIRC. Definitely something doable

[doup]

Hi! Thanks for the immense effort! I've started to review the PR and while I like the general approach, I don't like this at all: 😅

If it's OK I'll prepare a PR with a layer of proper semantic variables (+ I'll also try to define some color palettes). Maybe I'll move also the CSS vars near their usage when it makes sense, something like:

.layout {
  @media (prefers-color-scheme: dark) {
    --header-bg-color: var(--color-neutral-800);
    --header-border-color: #2c2c2d;
    --content-bg-color: var(--color-neutral-700);
  }

  @media (prefers-color-scheme: light) {
    --header-bg-color: var(--color-neutral-100);
    --header-border-color: var(--color-neutral-200);
    --content-bg-color: var(--color-neutral-50);
  }

  min-height: 100vh;
  display: flex;
  flex-direction: column;

  &__header {
    position: fixed;
    top: 0px;
    width: 100%;
    height: var(--header-height);
    background-color: var(--header-bg-color);
    border-bottom: 2px solid var(--header-border-color);
    z-index: $z-layout-header;
  }

  &__content {
    width: 100%;
    padding-top: var(--header-height);
    padding-bottom: 64px;
    flex-grow: 1;
    background-color: var(--content-bg-color);
  }
}

@include state-checked("mobile-menu") {
  // Disable scroll on main content
  .layout {
    height: 100%;
    overflow: hidden;
  }
}

[doup]

I've prepared a couple of PRs:

1. Sync with main lynnpepin/bevy-website#1
2. Refactor CSS tokens to be more "semantic" lynnpepin/bevy-website#2 Adds an extra layer of CSS vars (tokens) that are CSS component specific. Colors definition is not changed between dark/light mode.

[lynnpepin]

Hi! Thanks for the immense effort! I've started to review the PR and while I like the general approach, I don't like this at all: 😅

If it's OK I'll prepare a PR with a layer of proper semantic variables (+ I'll also try to define some color palettes). Maybe I'll move also the CSS vars near their usage when it makes sense, something like:

No qualms at all from my end, this is awesome and I appreciate this :D 👍🏻👍🏻👍🏻

[alice-i-cecile]

Closing to keep this tracked cleanly in #1771 :)