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.
### Improve usage experienceUse 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.
The import path within MediaWiki is relative and not developer friendly: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
// From a file in an extension.@opacity-base: 1;
@import ( reference ) '../../../../resources/lib/codex-design-tokens/theme-wikimedia-ui.less';@opacity-medium: 0.67;
@opacity-low: 0.33;
@opacity-transparent: 0;
// etc etc for every Codex token
```
You shouldn't need to figure out the relative path per-file.
=== ProposalsAnd a skin's `mediawiki.skin.variables.less` would look like this:
==== 1. Add Codex tokens directory to ResourceLoader Less import```lang=less
Provide a "magic" @import path that points to the right theme's tokens. E.g. people write `@import 'codex-design-tokens'mediawiki.skin.defaults.less';` and that ends up importing theme-wikimedia-ui.less in Minerva or theme-wikimedia-ui-legacy.less in Vector. (In practice, we would do this through the same mechanism as the skin variables system: each skin adds a custom import path to the Less import paths list, and each skin would place a file called codex-design-tokens.less in that path that imports the correct file.)
==== 2.// Import Codex tokens for the appropriate theme: wikimedia-ui for 16px skins, Reuse `mediawiki.skin.variables` ResourceLoader functionality and import permedia-ui-legacy for 14px skins
Do something like #1 but make it part of skin's mediawiki.skin.variables.less, so that code that does `@import 'mediawiki.skin.variables'` automatically gets all the right Codex tokens with the right theme along with it.@import '../../../../resources/lib/codex-design-tokens/theme-wikimedia-ui-legacy.less';
Preconditions:
- provide a sane skin default variables list in mediawiki.skin.defaults.less. It features a non-Wikimedia look and feel when newly installing core and a non-Wikimedia theme. Best starting idea for this skin theme is to orient on HTML/CSS defaults// Override any token values where needed:
- make skin overrides with all our current Codex tokens work,@border-radius-circle: 50%; therefore the same var must be avail in mediawiki.skin.defaults.less
Codex is already set up right now to have all tokens needed for Vector (theme-wikimedia-ui-legacy.less)/Vector 2022 and MinervaNeue (theme-wikimedia-ui.less)// Original value in Codex: 100%
```
For other often used themes like Monobook or Timeless we'd have to either add themes and make the authors/communities aware or depending on feedback take them into list for above.
### Document usage
We should add a section toupdate the [[ https://www.mediawiki.org/wiki/Codex | Codex page on mediawiki.org ]] to explain how to access the tokens from a Less file or style tag.:
- 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
[ ] Add neutral values for each token to `mediawiki.skin.defaults.less`
- [] Improve process of accessing tokens[ ] Add a unit test that verifies that every Codex token has a corresponding variable in `mediawiki.skin.defaults.less`
[ ] 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)
[ ] Vector-2022 (wikimedia-ui-legacy theme)
[ ] MinervaNeue (wikimedia-ui theme)
[ ] 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 ) );
```