diff --git a/doc/adr/0002-use-css-custom-properties.md b/doc/adr/0002-use-css-custom-properties.md new file mode 100644 index 000000000..d8e6edd60 --- /dev/null +++ b/doc/adr/0002-use-css-custom-properties.md @@ -0,0 +1,26 @@ +# 2. Use CSS custom properties in Vector + +Date: 2023-10-23 + +## Status + +Accepted. + +## Context + +In the context of the [Accessibility for Reading project](https://www.mediawiki.org/wiki/Reading/Web/Accessibility_for_reading) we needed a way to enable font-size customization in Vector in a scalable way. CSS custom properties were the mechanism chosen to enable this functionality. Full discussion available on [T346072](https://phabricator.wikimedia.org/T346072). + +## Decision +CSS Custom properties will be implemented in Vector on a very tightly scoped basis. The implementation assumes that we will eventually want to up-stream CSS custom properties to MediaWiki core/Codex. + +In order to facility an eventual migration, the following implementation measures will be taken: + +- CSS custom properties will be used *only* when needed for client-size customization. +- CSS custom properties will be grouped in the following file + `resources/skins.vector.styles/CSSCustomProperties.less`. +- CSS custom properties will maintain consistency with the naming convention of Codex design tokens. +- When possible, we'll assign CSS custom properties to existing Codex token values. + +## Consequences + +CSS Custom properties will be marked as `@private` and `@experimental` in the spirit of the [Stable interface policy/Frontend](https://www.mediawiki.org/wiki/Stable_interface_policy/Frontend) in order to discourage usage outside of Vector. This could be changes to `@internal` if usage outside of Vector is deemed necessary. \ No newline at end of file diff --git a/resources/skins.vector.styles/CSSCustomProperties.less b/resources/skins.vector.styles/CSSCustomProperties.less new file mode 100644 index 000000000..9a8d13e2c --- /dev/null +++ b/resources/skins.vector.styles/CSSCustomProperties.less @@ -0,0 +1,32 @@ +/** + * Vector CSS Custom properties + * ---------------------------- + * Please be aware that these properties are accessible via *any* client-side code. + * These variables should mirror Codex design token names and values: + * https://doc.wikimedia.org/codex/latest/design-tokens + * Only include properties that are required for client-side modification. + * + * @private - Currently, these variables are only intended for use by Vector 2022, + * however, they are designed to mimic the naming convention in Codex tokens + * in order to facilitate an eventual migration to a centralized source. + * @experimental + * @since October 2023 (MediaWiki 1.42) + */ + +:root { + --font-size-medium: unit( @font-size-small, rem ); +} + +// FIXME: Migrate `enabled` to `1`. +.vector-feature-custom-font-size-clientpref-enabled, +.vector-feature-custom-font-size-clientpref-1 { + --font-size-medium: unit( @font-size-medium, rem ); +} + +.vector-feature-custom-font-size-clientpref-2 { + --font-size-medium: unit( @font-size-large, rem ); +} + +.vector-feature-custom-font-size-clientpref-3 { + --font-size-medium: unit( @font-size-x-large, rem ); +} diff --git a/resources/skins.vector.styles/skin.less b/resources/skins.vector.styles/skin.less index 6d54fe1c8..9973e89f5 100644 --- a/resources/skins.vector.styles/skin.less +++ b/resources/skins.vector.styles/skin.less @@ -4,6 +4,7 @@ */ @import './variables.less'; @import './mixins.less'; +@import './CSSCustomProperties.less'; @media screen { .vector-feature-zebra-design-disabled { diff --git a/resources/skins.vector.styles/typography.less b/resources/skins.vector.styles/typography.less index 999d090cf..4db06b764 100644 --- a/resources/skins.vector.styles/typography.less +++ b/resources/skins.vector.styles/typography.less @@ -81,26 +81,12 @@ pre, } .vector-body { - font-size: @font-size-base; // Support IE 9-11, Trident cuts values 2 digits after decimal point. // `calc` enables to set correct calculation in place again. See T102364. font-size: @font-size-base--trident-hack; + font-size: var( --font-size-medium ); line-height: @line-height-base; - // FIXME: Migrate `enabled` to `1`. - .vector-feature-custom-font-size-clientpref-enabled, - .vector-feature-custom-font-size-clientpref-1 & { - font-size: 16px; - } - - .vector-feature-custom-font-size-clientpref-2 & { - font-size: 24px; - } - - .vector-feature-custom-font-size-clientpref-3 & { - font-size: 40px; - } - #siteSub { font-size: 12.8px; // T311421 }