From 7cfdbd196fc3122ca723d1962a41fdd2d3563d1a Mon Sep 17 00:00:00 2001 From: Jan Drewniak Date: Mon, 29 Jan 2024 12:47:07 -0500 Subject: [PATCH] Add ADR for CSS custom properties in Minerva Adds an ADR explaining the intent of use CSS custom properties for night mode in Minerva. Bug: T356074 Change-Id: I3a67f31ec426a3bb29e36c45adbcc0122e673d85 --- adr/0002-CSS-custom-props-for-night-mode.md | 94 +++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 adr/0002-CSS-custom-props-for-night-mode.md diff --git a/adr/0002-CSS-custom-props-for-night-mode.md b/adr/0002-CSS-custom-props-for-night-mode.md new file mode 100644 index 000000000..7516bcfbc --- /dev/null +++ b/adr/0002-CSS-custom-props-for-night-mode.md @@ -0,0 +1,94 @@ +# 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. \ No newline at end of file