=== Background & Goal
MediaWiki core, skins, extensions and external libraries are coming from all different contributors with all different z-index internal logics.
We need to provide a unified `z-index` stack for skins and extensions via central variables.
That would take a lot of burden from developers.
What is to win from a central agreed-on stack:
Such issues should be prevented in future:
{F36910728 width=50%}
== Proposal
As Less output:
```lang=less
// Page layout tokens
@z-index-bottom: -100;
@z-index-base: 0;
@z-index-above-content: 1;
@z-index-toolbar: 2;
@z-index-dropdown: 50;
@z-index-sticky: 100;
@z-index-fixed: 200;
@z-index-off-canvas-backdrop: 300;
@z-index-off-canvas: 350;
@z-index-overlay-backdrop: 400;
@z-index-overlay: 450;
@z-index-tooltip: 800;
@z-index-toast-notification: 900;
@z-index-top: 9999;
// Stacking-specific tokens for use in components.
@z-index-stacking-0: 0;
@z-index-stacking-1: 1;
@z-index-stacking-2: 2;
@z-index-stacking-3: 3;
```
We're mixing two different approaches and use cases in the proposal above:
1. The page layout (everything besides stacking in 2.)
2. The direct stacking layout context (for example in Codex ButtonGroup)
=== Developer notes
**Note, that we might need to be careful when rolling out the change as it could possibly impact Vector with its “sticky” (fixed) header**
Note, while another size token is called -absolute-9999, it seems counter productive here, as it will end up in an arms race like recently in [[ https://gerrit.wikimedia.org/r/c/mediawiki/extensions/Kartographer/+/889504/5/modules/dialog/dialog.less#149 | Kartographer ]] with `z-index: 9999999`.
=== Acceptance criteria for Done
[x] Settle on a clear stack for Codex and Wikimedia products with help of POC patches
[x] Bring to Codex
[] ~~Bring to WikimediaUI Base~~ Decided to prioritize on replacing Base with Codex tokens T334934
[x] Bring to MediaWiki core by help of Codex design tokens containing mediawiki.skin.variables
[] Use in Wikimedia deployed skins
[x] Use in Vector
[x] MobileFrontend and
[x] MinervaNeue
[] MonoBook
[] Example
[] Other skins?
[] Use exemplarily in an extension (Growth's Newcomer Homepage seems like a good candidate due to big variety of z-indizes in use)
---
---
=== Previous implementations
==== Current Codex design decision tokens
```lang=less
@z-index-base: 0;
@z-index-overlay: 101;
```
**MinervaNeue**
From [[ https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/skins/MinervaNeue/+/refs/heads/master/minerva.less/minerva.variables.less | minerva.less/minerva.variables.less ]]
```lang=less
// z-index:
@z-indexOccluded: -1;
@z-indexBase: 0;
@z-indexAboveContent: 1;
@z-indexDrawer: 2;
@z-indexOverlay: 3;
@z-indexOverOverlay: 4;
```
**ContentTranslation**
comes with its own `z-index` system
**Popups**
features for example `z-index: 1000` on `#mwe-popups-settings` [[ https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/Popups/+/refs/changes/41/852941/1/src/ui/variables.less | and ]]
```lang=less
@zIndexPopup: 110;
@zIndexBackground: 111;
@zIndexForeground: 112;
@zIndexThumbnailMask: 113;
```
=== External libraries
- External libraries:
-- **Bootstrap v5.3 **
```lang=sass
$zindex-dropdown: 1000;
$zindex-sticky: 1020;
$zindex-fixed: 1030;
$zindex-offcanvas-backdrop: 1040;
$zindex-offcanvas: 1045;
$zindex-modal-backdrop: 1050;
$zindex-modal: 1055;
$zindex-popover: 1070;
$zindex-tooltip: 1080;
$zindex-toast: 1090;
```
- **[[ https://designsystem.digital.gov/design-tokens/z-index/ | US Web Design System ]]**
```lang=less
'auto': auto
'top': 99999
500: 500
400: 400
300: 300
200: 200
100: 100
0: 0
'bottom': -100
```
**Further resources**
- https://www.smashingmagazine.com/2021/02/css-z-index-large-projects/
I personally don't find the approach here convincing in details.
```lang=js
// Page Layout
export const zLayoutNavigation = above + base;
export const zLayoutFooter = above + base;
export const zLayoutModal = above + zLayoutNavigation;
export const zLayoutPopUpAd = above + zLayoutModal;
```
Having constants with calculations leads to unexpected results in my experience. Bootstrap's and USWDS try to provide a general expectable solution that still leaves flexibility in context, without relying on contextual computations.
- https://css-tricks.com/systems-for-z-index/