mirror of
https://gerrit.wikimedia.org/r/mediawiki/skins/MinervaNeue
synced 2024-11-16 18:58:45 +00:00
7cfdbd196f
Adds an ADR explaining the intent of use CSS custom properties for night mode in Minerva. Bug: T356074 Change-Id: I3a67f31ec426a3bb29e36c45adbcc0122e673d85
94 lines
4.7 KiB
Markdown
94 lines
4.7 KiB
Markdown
# 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](https://en.wikipedia.org/wiki/Congress_of_the_Philippines)/sports team
|
|
colors or [articles about colors](https://en.wikipedia.org/wiki/Pantone#Color_of_the_Year) ). 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. |