The latest Codex build provides CSS variable support and a palette. Following T358059, we want to copy the approach in Minerva inside Vector 2022.
Changes to Codex in v1.5.0
Codex 1.5.0 will ship with a number of important updates for dark mode support. Some minor changes will need to be made to Vector and Minerva skins in order to integrate with these changes.
CSS Variables are used by default; "experimental" build has been removed
Codex 1.5.0 removes all references to an "experimental" build of the library (both styles and design tokens). Instead, the default build of Codex design tokens and styles are now aware of a set of publicly-exposed CSS custom properties (pertaining to color), and will respect any changes to those properties in the browser environment.
In @wikimedia/codex-design-tokens 1.5.0, the theme-wikimedia-ui.less file will include a number of variables that look like this:
@color-base: var( --color-base, #202122 ); @color-base--hover: var( --color-base--hover, #404244 ); // Aimed to be replaced by `color.gray600` in future. @color-emphasized: var( --color-emphasized, #000 ); @color-subtle: var( --color-subtle, #54595d ); @color-placeholder: var( --color-placeholder, #72777d ); @color-disabled: var( --color-disabled, #72777d ); @color-inverted: var( --color-inverted, #fff );
All LESS variables which relate to color will get their value from a lookup of the corresponding CSS custom property: @color-base will look for the value of --color-base, etc. The CSS custom property names are *not* namespaced FWIW. LESS variables which do not relate to color are unchanged (they don't reference CSS custom props at this time).
For backwards-compatibility, we are also including the normal token value here as a fallback, so users of the design tokens who don't care about supporting alternate color modes can just keep using the tokens in the same way as before.
As of Codex 1.5.0, the @wikimedia/codex component styles are built using these updated design token values. So component styles will be aware of the CSS custom properties as well, and will respect the new values of these properties when they change. The "experimental" component styles have been removed, so please update any skin code accordingly.
New CSS root declaration files
Codex design tokens v1.5.0 will include a new file called theme-wikimedia-ui-root.css. This file is the "root declaration" that defines the CSS custom properties relevant to color along with their default (light mode) values. The file looks like this:
:root { --color-base: #202122; --color-base--hover: #404244; /* Aimed to be replaced by `color.gray600` in future. */ --color-emphasized: #000; --color-subtle: #54595d; --color-placeholder: #72777d; --color-disabled: #72777d; --color-inverted: #fff; /* etc, full list ~110 color variables is included */ }
Similarly, there is a file called theme-wikimedia-ui-mode-dark.css which contains a set of variable overrides – these are the dark mode values which should override the above color variables when dark mode is active. Not every variable on the above list is overridden for various reasons.
:root { --color-base: #f8f9fa; --color-base--hover: #fff; /* Aimed to be replaced by `color.gray600` in future. */ --color-emphasized: #fff; --color-subtle: #eaecf0; --color-placeholder: #c8ccd1; --color-inverted: #101418; /* ... etc, full list contains about 50 css vars */ };
Mode-specific LESS mixins
As a convenience, @wikimedia/codex-design-tokens 1.5.0 will also include some LESS mixins which can be used to load one of the above sets of variables into an arbitrary CSS selector. There are two files:
- theme-wikimedai-ui-reset.less (a mixin which restores all CSS custom props to their light mode defaults, call it with .cdx-mode-reset())
- theme-wikimedia-ui-mixin-dark.less (a mixin which provides just the dark mode variables – call it with .cdx-mode-dark() ).
Usage in skins
The general approach taken in T358059 is still valid, but please use the above-mentioned files going forward. All references to "experimental" Codex tokens and styles should be removed.
Acceptance criteria
- Vector 2022 uses the Codex CSS build to get night mode
- Vector 2022 has a light mode color palette using the LESS variables e.g. `--color-base: @color-base;`
- Vector 2022 has a night mode color palette identical to Minerva's which is enabled when the .skin-theme-clientpref-night class is enabled on the HTML tag.
QA Steps
- Visiting any URL with ?vectornightmode=1