Now that the [[ https://www.npmjs.com/package/@wikimedia/codex-design-tokens | Codex design tokens package ]] has been released, it can be used within MediaWiki. We need to do a few things to enable developers to start using them there, and to make sure the correct theme is used for each skin.
### Use the skin variables system to distribute tokens
There's an existing system in MediaWiki core that lets skins override which file is used when `'mediawiki.skin.variables.less'` is imported. Each skin provides its own file. There is a base file in core called `mediawiki.skin.defaults.less` that contains default values for each variable. Each skin's `mediawiki.skin.variables.less` file imports the defaults file and then overrides some or all of the variables with its own values. There are currently 36 skin variables defined. 26 of them have the same names as tokens in Codex, while 10 of them either have a different name in Codex or aren't in Codex at all.
We will distribute the tokens through this system, by making every Codex token a skin variable. In each skin's `mediawiki.skin.variables.less`, we will import the Codex tokens for the appropriate theme. In `mediawiki.skin.defaults.less`, we will define "neutral" values for each Codex token, and we'll add a unit test to verify that no tokens are missing.
In the future, we would like to add these "neutral" values as a theme in Codex, so that the defaults file can just import that theme, but that's out of scope for this task.
To avoid breaking anything, we need to be careful to change the value of any existing skin variables without intending to. For the purposes of this task, we should keep the values of all the existing skin variables the same, overriding Codex token values where necessary. Later, we will try to harmonize these and remove overrides where possible, but that's also out of scope for this task.
Concretely, `mediawiki.skin.defaults.less` will look like this:
```lang=less
@opacity-base: 1;
@opacity-medium: 0.67;
@opacity-low: 0.33;
@opacity-transparent: 0;
// etc etc for every Codex token
```
And a skin's `mediawiki.skin.variables.less` would look like this:
```lang=less
@import 'mediawiki.skin.defaults.less';
// Import Codex tokens for the appropriate theme: wikimedia-ui for 16px skins, wikimedia-ui-legacy for 14px skins
@import 'mediawiki.skin.codex-design-tokens/theme-wikimedia-ui-legacy.less';
// Override any token values where needed:
@opacity-icon-base: 1; // Codex: 0.87
```
### Document usage
We should update the [[ https://www.mediawiki.org/wiki/Codex | Codex page on mediawiki.org ]]:
- To import the Codex tokens in MW, do `@import 'mediawiki.skin.variables.less';`
- Don't import from `@wikimedia/codex-design-tokens`
- Add this to the "Differences between Codex documentation and MediaWiki usage" table
---
## Acceptance criteria
[x] Enable use of tokens in MediaWiki
[x] Add neutral values for each token to `mediawiki.skin.defaults.less` https://gerrit.wikimedia.org/r/c/mediawiki/core/+/886929
[x] Add a unit test that verifies that every Codex token has a corresponding variable in `mediawiki.skin.defaults.less` https://gerrit.wikimedia.org/r/c/mediawiki/core/+/886929
[x] Create a way for skins to safely import the Codex theme of their choice, without having to rely on assumptions about the relative path between the skin and MW core https://gerrit.wikimedia.org/r/c/mediawiki/core/+/894132
[ ] In skins that should use the Codex tokens, import the tokens from the appropriate theme in `mediawiki.skin.variables.less`; but add overrides where needed so that the values of pre-existing skin variables don't change (we should reconsider these overrides later, but that can happen over time and isn't part of this task)
[ ] Vector (wikimedia-ui-legacy theme) https://gerrit.wikimedia.org/r/c/mediawiki/skins/Vector/+/886930
[ ] Vector-2022 (wikimedia-ui-legacy theme) https://gerrit.wikimedia.org/r/c/mediawiki/skins/Vector/+/886930
[ ] MinervaNeue (wikimedia-ui theme) https://gerrit.wikimedia.org/r/c/mediawiki/skins/MinervaNeue/+/886931
[ ] MonoBook? (should this use Codex tokens? which theme?)
[ ] Document usage instructions (started [[ https://www.mediawiki.org/wiki/Codex#Using_Codex_design_tokens | on mw.org ]] but needs updating once the process is improved)
---
---
== Original task scope
### ~~Enable usage~~ (✓ done)
**Update:** This was fixed in T326591
Currently, you should be able to import the tokens file relative to your location within MediaWiki. For example, from `extensions/VueTest/resources/codex-demos/Sandbox.vue`, I can do this:
```lang=html
<style lang="less">
@import ( reference ) '../../../../resources/lib/codex-design-tokens/theme-wikimedia-ui.less';
.cdx-sandbox {
background-color: @background-color-progressive;
}
</style>
```
However, when I tried this, I got the following error in the browser console:
```
/w/load.php?lang=en&modules=ext.vueTest.codexdemo%7Cjquery%2Coojs-ui-core%2Cvue&skin=minerva&version=1nm17 Less_Exception_Compiler: error evaluating function `rgba` color functions take numbers as parameters index: 1350
```
This seems to be caused by the Less compiler not liking use of `rgba()` with `calc` inside, like this:
```lang=less
@background-color-quiet--hover: rgba( 0, 24, 73, calc( 7 / 255 ) );
```