mediawiki-skins-MinervaNeue/adr/0002-CSS-custom-props-for-night-mode.md

1. Use CSS custom properties for night mode

Date: 2024-01-29

Status

Accepted.

Context

During the Night Mode Project, there was considerable debate as to how to technically achieve night mode given the ecosystem and infrastructure complexities of the Wikimedia ecosystem.

Considered approaches

Use the existing DarkMode gadget - This approach relies on using a CSS invert "hack" to invert all the colors on the rendered page and change them from light to dark. This was the initially proposed strategy, but it was later dropped for the following reasons:

• Semantic color distortion: Inverting all colors on the page would make certain colors incorrect. This would negatively impact Wikipedia content in a way that may make it wrong or confusing (e.g. inverting political party/sports team colors or articles about colors ). It was deemed that in principle, the Wikimedia foundation should not make these kinds of potentially negative changes to Wikimedia project content.
• Inability to measure impact: When inverting colors, we would have no way of measuring the amount of content that has been negatively impacted, and therefor would not be able to identify which content needs fixing.
• Lack of color palette customization: Inverting colors would not provide any flexibility for tweaking or modifying the night mode design. The resulting night mode would be an inverse of the light-mode, instead of a more nuanced design. Visual elements such as colors or white drop-shadows would be technically difficult to remove or modify.

Modify the existing Less variables - This approach would involve changing the values of the existing color variables in the Less CSS preprocessor based on night mode being enabled or disabled. Since Codex variables are widely used and overrideable by the skin, it would have broad ecosystem support. It was not pursued for the following reasons:

• Support for anonymous users: In order to serve night mode to anonymous users, we would have to generate a new night mode stylesheet, then serve that stylesheet conditionally for anonymous users based on whether they or not have night mode enabled. Due to our aggressive caching strategy, we are unable to vary which stylesheets we serve to anonymous users.

Use CSS custom properties for colors - This approach involves replacing the Less color variables required for night mode with CSS custom properties. Conditional code is then added to the stylesheet (either by media-query or class) that changes the value of these custom properties for night mode. Due to the constrains mentioned above, this is the preferred approach.

Decision

In order to create a night mode for the Minerva skin, the Web Team has decided to use CSS custom properties to achieve a customizable color palette.

We will replace the Less variables required for night mode with CSS custom properties. The values of these custom properties will remain unchanged for light-mode, but will be customized for night mode.

We agree that maintaining a single source of truth for Codex token values is important, so we will maintain the Codex naming convention for CSS custom properties and use values derived from Codex as much as possible.

Consequences

Benefits

• Performance - Night mode can be implemented by changing a relatively small set of CSS values.
• Better alignment with web standards - CSS custom properties are a standards-based solution with broad browser support.
• Better traceability & tooling. Unlike Less variables, changes to CSS custom properties are easily traceable via the browser console.
• Better support for system-level settings - CSS custom properties can respond to the prefers-color-scheme media-query, which will allow us to enable/disable night mode based on system-level settings. In future, we can also respond to other accessibility media-queries such prefers-contrast.

Drawbacks

Although the Minerva skin can implement CSS custom properties with relative ease, we acknowledge that the Mediawiki ecosystem depends on on a broad range of extensions, and for these to function well in night mode, they too will have to adopt the same CSS custom properties as the Minerva skin. We commit to helping these migration by providing strategies, documentation and tooling around the expect use of CSS custom properties for night mode.

Similarly, we acknowledge that templates will also have to be modified to work with this night mode strategy. We commit to creating plans or strategies to help template authors with these modifications.