Devise a generic way for theme-agnostic stylesheets to adapt to the current theme
Closed, ResolvedPublic
Actions

Assigned To

Authored By

	matmarex
	Sep 16 2015, 12:56 PM

Description

Goal

MediaWiki skins should be able to render MediaWiki own widgets and possibly also OOUI or other UI components in skin-specific styles.
Imagine a widget with WikimediaUI theme styles for Vector and MinervaNeue and Apex theme style for MonoBook.

Problem statement

I would like it if there was a way to provide OOUI-theme-specific styles in regular ResourceLoader modules shipped with MediaWiki.

My use case is the DateInputWidget. It is styled specifically for the default WikimediaUI theme, and while it looks neat there, it looks out of place elsewhere:

WikimediaUI themed default look in Vector	Apex-theme using skin Monobook

(That is actually not quite as awful as I was afraid, but still.)

Proposed solution

See also T112747#4093591, this is just the short summary of implemented path:

1. Add a MediaWiki core solution that will offer sane defaults for all design-approved, naming convention following variables (and require them to be defined) – defined in core's 'resources/src/mediawiki.less/mediawiki.skin.defaults.less'
2. Add skin-specific @import feature that offers to redefine values accordingly in all Wikimedia Foundation deployed skins – defined in skin's 'resources/mediawiki.less/mediawiki.skin.variables.less'

Instructions for skins

// In skin.json, add:
//    "SkinLessImportPaths": {
//        "skinname": "resources/mediawiki.less"
//    }
//
// Create a file called resources/mediawiki.less/mediawiki.skin.variables.less, which starts with:
//    @import 'mediawiki.skin.default.less';
// followed by any overrides for these variables, e.g.:
//    @width-breakpoint-desktop: 1234px;

In follow-ups to this task

Bring mediawiki.skin.variables to all Wikimedia deployed skins
Import WikimediaUI Base variables in Vector's 'mediawiki.skin.variables.less' file
Import WikimediaUI Base variables in MinervaNeue's
Use OOUI's Apex theme variables in Monobook's import

Details

Subject	Repo	Branch	Lines +/-
Implement mediawiki.skin.variables.less for Vector	mediawiki/skins/Vector	master	+22 -1
resourceloader: Inject @skin-folder-name for theme-agnostic style sheets	mediawiki/core	master	+31 -0
Provide theme-agnostic style variables	mediawiki/core	master	+192 -0
resourceloader: Add skin-based 'mediawiki.skin.variables.less' import	mediawiki/core	master	+163 -33
Implement mediawiki.skin.variables.less for MonoBook	mediawiki/skins/MonoBook	master	+14 -0
Use wikimedia.ui from core	mediawiki/skins/MinervaNeue	master	+1 -8
resources: Provide theme-agnostic style variables	mediawiki/core	master	+9 -0
mediawiki.variables: Add @border-radius-base	mediawiki/core	master	+7 -2
mediawiki.variables: Add @font-family-sans	mediawiki/core	master	+5 -0

Customize query in gerrit

Related Objects
Search...

Status	Assigned	Task
Open	None	T112933 DateInputWidget looks ugly in Apex theme
Open	None	T113560 Standardize MediaWiki components (tracking)
Resolved	Krinkle	T112747 Devise a generic way for theme-agnostic stylesheets to adapt to the current theme
Resolved	Volker_E	T263270 Implement mediawiki.skin.variables for MinervaNeue

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

Change 298637 had a related patch set uploaded (by Bartosz Dziewoński):
mw.widgets.DateInputWidget: Add Apex-theme-specific styles

https://gerrit.wikimedia.org/r/298637

gerritbot added a project: Patch-For-Review.Jul 12 2016, 9:20 PM

Krinkle mentioned this in T140804: Remove $wgResourceLoaderLESSVars and ResourceLoaderGetLessVars hook.Jul 19 2016, 6:56 PM

Krinkle renamed this task from Devise a way to provide OOUI-theme-specific styles in regular ResourceLoader modules to Devise a generic way for theme-agnostic stylesheets to adapt to the current theme.Jul 19 2016, 7:05 PM

Proposal:

Define a set of standard variables (and maybe some functions/mixins) that will have default values that individual skins (or their OOjs UI themes) can override.
Provide a way to import that from any less module (e.g. make that part of the current skin/theme available as public import path).

For example:

Defaults in mediawiki-core:/resources/src/mediawiki.less/theme/defaults.less. Importable as @import theme/defaults.less. An empty file that just imports this would be at mediawiki-core:/resources/src/mediawiki.less/theme/theme.less.

By default, if a skin registers no OOUI theme and no custom theme file, @import theme.less will import that. Otherwise, it will resolve to the current skin's theme file.

Assuming we'll make OOUI's defaults are equal or a superset of what MediaWiki standardises, skins that register an OOUI theme (SkinOOUIThemes) won't need to do anything. Other skins can provide their theme file via a new config (e.g. SkinThemeDir: { skinname: path } or something).

Krinkle added a project: Front-end-Standards-Group.Jul 19 2016, 7:16 PM

Krinkle mentioned this in T140807: Remove $wgResourceLoaderLESSImportPaths.Jul 19 2016, 7:25 PM

Krinkle added a parent task: T140807: Remove $wgResourceLoaderLESSImportPaths.

matmarex removed matmarex as the assignee of this task.Jul 20 2016, 6:49 PM

matmarex removed a project: Patch-For-Review.

That sounds nice, but I am not convinced that it will be sufficient to express the stylistic differences even between the two built-in themes (Apex and MediaWiki), much less any third-party ones (if anyone ever creates them). :/

@Krinkle I like the proposal, in one little note: I think it's overkill to have both, defaults.less and theme.less. theme.less seems sufficient to me carrying the variables.

In T112747#2498997, @Volker_E wrote:

@Krinkle I like the proposal, in one little note: I think it's overkill to have both, defaults.less and theme.less. theme.less

I suggested having both as otherwise it would greatly complicate versioning and future changes. If we start with 2 variables and then later "add" another (btw, what would "add" mean without a default), all skins would need to implement it, otherwise we can't safely reference it anywhere without risking fatal errors.

@Krinkle Ok, but that would refer to the mediawiki.less/default.less only, not to a theme, or? As it are Less variables, if a theme doesn't implement it, it would fallback to the default.less if it's not available in theme/theme.less?!

Volker_E added a project: UI-Standardization-Kanban.Sep 14 2016, 7:03 PM

Restricted Application added a project: UI-Standardization. · View Herald TranscriptSep 14 2016, 7:03 PM

Volker_E mentioned this in T145894: WikimediaUI Base: Align colors to overhauled color palette.Sep 20 2016, 5:03 PM

Volker_E mentioned this in M82: Color palette (Wikimedia Design Style Guide/WikimediaUI).Dec 16 2016, 12:54 AM

Volker_E added a parent task: T123359: Provide WikimediaUI Base's tokens in Wikimedia Design Style Guide following skins.

SamanthaNguyen subscribed.Dec 16 2016, 12:59 AM

At M82 @Jdlrobson wrote:

@Volker_E What's the problem with having resources/wikimedia-base.less which is a copy and paste of the current distribution of your wikimedia-base repo (in absence of being able to use a package manager) - we do this for jquery and other files?

mediawiki.ui/variables.less can import from the new file to keep its contract but move us away from using that.

e.g. @mediaWikiVarible: @wikimedia-ui-variable

I will happily help migrate us away from mediawiki ui variables if that's what's needed but I worry about having all these places to look...

The problem is in my current understanding, that we shouldn't necessarily provide a WikimediaUI theme as default for MediaWiki from a software product point of view. Two related issues are problematic from my point of view:

The bundling of MW to Foundation use cases, where a default (empty) theme is a more-free out-of-the-box state.
A lot of problems that we're solving on the technical side are also resembled on the UI/presentational side and it's hard to come up with another default variant aside of WikimediaUI, given our scarce resources. Exemplified at the color palette M82, a useful production-ready accessible alternative palette is technically very hard to achieve.

Jdlrobson unsubscribed.Jan 4 2017, 12:51 AM

Volker_E moved this task from Inbox to Backlog on the Front-end-Standards-Group board.Feb 8 2017, 7:36 PM

Volker_E moved this task from Backlog to Accepted on the Front-end-Standards-Group board.

Change 345440 had a related patch set uploaded (by VolkerE):
[mediawiki/core@master] Provide theme-agnostic style variables

https://gerrit.wikimedia.org/r/345440

gerritbot added a project: Patch-For-Review.Apr 4 2017, 7:08 PM

Volker_E moved this task from Backlog to Doing on the OOUI board.Apr 7 2017, 12:19 AM

Krinkle moved this task from Backlog to Accepted Enhancement on the MediaWiki-ResourceLoader board.Apr 11 2017, 12:24 AM

Krinkle added a parent task: T140804: Remove $wgResourceLoaderLESSVars and ResourceLoaderGetLessVars hook.Apr 11 2017, 12:45 AM

Krinkle removed a parent task: T140804: Remove $wgResourceLoaderLESSVars and ResourceLoaderGetLessVars hook.

Jdforrester-WMF updated the task description. (Show Details)May 20 2017, 8:29 AM

Blocked by T123359: Provide WikimediaUI Base's tokens in Wikimedia Design Style Guide following skins?

SamanthaNguyen unsubscribed.Aug 29 2017, 5:05 AM

In T123359#3543114, @Jdforrester-WMF wrote:

What's left to do before this can be marked Resolved? Actual inheritance and use in legacy code like SpecialSearch.php and frameworks like MWUI?

Renewed proposal below, based on feedback from later comments and in-person with @Volker_E last week.

Goal

The end-result is that any Less stylesheet loaded by ResourceLoader can do @import 'mediawiki.theme.variables'; and that would provide theme variables associated with the current MediaWiki skin. The skin in turn may delegate to something else, like wikimedia-ui-base, or OOUI, or perhaps even derived from other libs' (eg. Bootstrap).

Take note here that ResourceLoader modules by design, already vary by skin, with existing features such as skinStyles, skinScripts, getLessVars($context), and getStyles($context) all varying by skin.

Implementation

Currently, ResourceLoader instantiates Less_Parser with a mostly empty ImportPaths array. (Albeit extendable via the deprecated wgResourceLoaderLESSImportPaths, T140807.)

My proposal is to make ResourceLoaderFileModule dynamically add one entry to this array based on the current skin.

The skin would declare (perhaps via skin.json) where its mediawiki.theme file(s) are.

At run-time, from the perspective of a random style module, import paths could end up as follows:

[
 "/resources/src/mediawiki.less/", # mediawiki.mixins, mediawiki.theme, mediawiki.theme.default
 "/skins/Vector/mediawiki.less/" # mediawiki.theme
]

MediaWiki core's mediawiki.theme.less file would be an empty placeholder proxying default, for cases where the skin does not register a theme file. The default file would be the place where we declare the "standard variable" names, a bit of documentation, with generic (unpinionetad) value as default (perhaps like a CSS reset, or with initial and inherit keywords).

core/.../mediawiki.less/mediawiki.theme.less

@import "mediawiki.theme.default"

Vector's mediawiki.theme.less file would shadow this file with its own, which could look like this:

Vector/mediawiki.less/mediawiki.theme.less

@import "mediawiki.theme.default"
@import "wikimedia-ui-base"

Other skins could potentially place direct variable assignments here instead.

Standard variables

The part I'm not yet sure of is which variable names we're going to define in the theme file. In other words, which variables should be standardised as shared across skins.

(master) wikimedia-ui-base.less defines 106 variables.
(master) oojs-ui/.../blank/common.less defines 7 variables.
- (master) oojs-ui/.../apex/common.less defines 7 variables and 43 additional.
- (master) oojs-ui/.../wikimediaui/common.less defines 7 variables and 111 additional.

I'm gonna leave that for during Code Review for now. I guess when we write this we should start with a single use case in mind that we can use to test it with (e.g. a particular place in core or an extension where we want to use a skin-dependent variable that we can also agree on can be set by multiple skins).

Restricted Application added a project: Performance-Team. · View Herald TranscriptMar 30 2018, 1:17 AM

Krinkle mentioned this in T123359: Provide WikimediaUI Base's tokens in Wikimedia Design Style Guide following skins.Mar 30 2018, 1:18 AM

• Imarlier moved this task from Inbox, needs triage to Radar on the Performance-Team board.Apr 2 2018, 8:22 PM

• Imarlier edited projects, added Performance-Team (Radar); removed Performance-Team.

Krinkle removed a parent task: T140807: Remove $wgResourceLoaderLESSImportPaths.Apr 10 2018, 7:26 PM

Krinkle moved this task from Limbo to Watching on the Performance-Team (Radar) board.Apr 26 2018, 12:12 AM

Change 434211 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] [WIP] resourceloader: Add skin-based 'mediawiki.variables' import for LESS

https://gerrit.wikimedia.org/r/434211

Change 434212 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] mediawiki.variables: Add @font-family-sans

https://gerrit.wikimedia.org/r/434212

Change 434214 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/skins/Vector@master] Implement mediawiki.variables for Vector

https://gerrit.wikimedia.org/r/434214

Change 434215 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/skins/MonoBook@master] Implement mediawiki.variables for MonoBook

https://gerrit.wikimedia.org/r/434215

Change 434213 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] mediawiki.variables: Add @border-radius-base

https://gerrit.wikimedia.org/r/434213

Change 434212 abandoned by Krinkle:
mediawiki.variables: Add @font-family-sans

Reason:
Combined with Icf86c930a3b5524254

https://gerrit.wikimedia.org/r/434212

Change 434213 abandoned by Krinkle:
mediawiki.variables: Add @border-radius-base

Reason:
Combined with Icf86c930a3b5524254

https://gerrit.wikimedia.org/r/434213

Implementing SkinLessVariablesImportPaths would be valuable for Theme (https://www.mediawiki.org/wiki/Extension:Theme). For example, v4 of the Refreshed skin relies heavily on a custom set of LESS mixins. If Refreshed could give extensions easy access to those mixins through ResourceLoader, writing custom themes for Refreshed would be much easier.

Krinkle mentioned this in T198339: ResourceLoaderImageModule should be able to pull colours from core themes by name.Jun 6 2019, 10:07 AM

daniel mentioned this in T122924: Merge Extension:Theme into core.Jul 26 2019, 11:31 AM

• Demian subscribed.Feb 16 2020, 3:06 AM

Food for thought:
Theming that's done in LESS cannot be hot-swapped client-side.

Different color themes for skins are not practical to be swapped server-side. That would result in multiplied cache requirements and a full stylesheet reload when switching themes.
Only CSS that concerns branding, logo, website-specific style elements are practical to be placed into a server-side "theme". That would benefit mostly non-WMF operators of MediaWiki instances, though.

• Demian mentioned this in T245684: Enable importing wikimedia-ui-base.less in skins, extensions.Feb 19 2020, 10:44 PM

Change 579425 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/skins/MinervaNeue@master] Use wikimedia.ui from core

https://gerrit.wikimedia.org/r/579425

Change 579857 had a related patch set uploaded (by Aron Manning; owner: Aron Manning):
[mediawiki/core@master] Provide theme-agnostic style variables

https://gerrit.wikimedia.org/r/579857

Change 579858 had a related patch set uploaded (by Aron Manning; owner: Aron Manning):
[mediawiki/core@master] Separate wikimedia-ui-base.less resource from OOUI into its own folder

https://gerrit.wikimedia.org/r/579858

Change 580558 had a related patch set uploaded (by Aron Manning; owner: Aron Manning):
[mediawiki/core@master] resources: Enable skins to override theme-agnostic style variables

https://gerrit.wikimedia.org/r/580558

Summary from @Krinkle on Gerrit:

The import directories will be injected by ResourceLoader.
Each skin and core will have its own "mediawiki.theme" directory, the name stays the same.
If the current skin provides "mediawiki.theme/variables" then that one is used. A skin would typically start with default.less to ensure all base variables are defined and then override as-needed, possibly using wikimedia-ui such as for Vector and Minerva.
If the skin doesn't (yet), then core's variable.less file is imported (which just includes defaults.less).
Then, anywhere in the system, in an extension or in core, without needing to know about skins, you import "mediawiki.theme/variables" and can then utilize the correct values automatically.

Importpath-based override of 'mediawiki.theme/variables' would result in a deep path for only a single file in skins, such as:
Vector/mediawiki.less/mediawiki.theme/variables.less this is necessary to avoid adding other files to the lookup path.

Another option would be if RL implicitly loaded the override from the skin, eg.:
Vector/mediawiki.theme/variables.less
This is very likely to be confusing to developers without the intricate knowledge of this RL behaviour:
it won't be understood why some variables (those overridden) have different values than defined in core.

One solution to this is to make the import explicit. That requires that the import path depends on the active skin. The active skin can be injected as a variable by RL as demonstrated in a POC (it is usual to import themes with this construct): Patch 580558.

Krinkle mentioned this in T56864: ResourceLoader: Implement support for LESS in wiki modules (user and site), supporting e.g. MediaWiki:Common.less.May 20 2020, 5:24 PM

Change 579857 had a related patch set uploaded (by Aron Manning; owner: Aron Manning):
[mediawiki/core@master] resources: Provide theme-agnostic style variables

https://gerrit.wikimedia.org/r/579857

Change 579857 abandoned by Aron Manning:
resources: Provide theme-agnostic style variables

Reason:
Discussion relevant to ticket

https://gerrit.wikimedia.org/r/579857

Change 579425 abandoned by Jdlrobson:
Use wikimedia.ui from core

https://gerrit.wikimedia.org/r/579425

Change 434211 merged by jenkins-bot:
[mediawiki/core@master] resourceloader: Add skin-based 'mediawiki.skin.variables.less' import

https://gerrit.wikimedia.org/r/434211

Change 434215 merged by jenkins-bot:
[mediawiki/skins/MonoBook@master] Implement mediawiki.skin.variables.less for MonoBook

https://gerrit.wikimedia.org/r/434215

Restricted Repository Identity mentioned this in rSMNB0fe9a862718a: Implement mediawiki.skin.variables.less for MonoBook.Sep 16 2020, 3:16 PM

ReleaseTaggerBot added a project: MW-1.36-notes (1.36.0-wmf.10; 2020-09-22).Sep 16 2020, 4:00 PM

Change 434214 merged by jenkins-bot:
[mediawiki/skins/Vector@master] Implement mediawiki.skin.variables.less for Vector

https://gerrit.wikimedia.org/r/434214

Is this causing CI failures in MF: https://gerrit.wikimedia.org/r/c/mediawiki/extensions/MobileFrontend/+/627877?

Jdlrobson mentioned this in T263064: Fix our storybook instances.Sep 16 2020, 9:22 PM

Volker_E added a subtask: T263270: Implement mediawiki.skin.variables for MinervaNeue.Sep 18 2020, 4:18 PM

Change 345440 abandoned by Krinkle:
[mediawiki/core@master] Provide theme-agnostic style variables

Reason:
Superseded by <https://gerrit.wikimedia.org/r/c/mediawiki/core/ /434211>

https://gerrit.wikimedia.org/r/345440

Change 580558 abandoned by Krinkle:
[mediawiki/core@master] resourceloader: Inject @skin-folder-name for theme-agnostic style sheets

Reason:
Superseded by <https://gerrit.wikimedia.org/r/c/mediawiki/core/ /434211>

https://gerrit.wikimedia.org/r/580558

Jdlrobson closed subtask T263270: Implement mediawiki.skin.variables for MinervaNeue as Resolved.Dec 16 2020, 6:12 PM

BEANS-X2 subscribed.Jan 29 2021, 10:52 AM

Volker_E updated the task description. (Show Details)Mar 16 2021, 11:27 PM

Restricted Application added a subscriber: Masumrezarock100. · View Herald TranscriptMar 16 2021, 11:27 PM

Volker_E edited parent tasks, added: T113560: Standardize MediaWiki components (tracking); removed: T123359: Provide WikimediaUI Base's tokens in Wikimedia Design Style Guide following skins.Mar 16 2021, 11:58 PM

Resolving with MediaWiki v1.36 successfully.

Volker_E updated the task description. (Show Details)Mar 17 2021, 12:10 AM

Krinkle mentioned this in T265941: Document how mediawiki.skin.variables works.Nov 29 2021, 7:23 PM

Krinkle mentioned this in T296379: GrowthExperiments: Less_Exception_Parser: File `resources/lib/ooui/wikimedia-ui-base.less` not found.Nov 29 2021, 7:29 PM

kostajh mentioned this in T297008: Replace wikimedia-ui imports with mediawiki.skin.variables.Dec 3 2021, 1:37 PM

Michael mentioned this in T313166: new Lexeme creation page uses a font different from the rest of the site.Jul 20 2022, 11:22 AM

Devise a generic way for theme-agnostic stylesheets to adapt to the current themeClosed, ResolvedPublicActions

Description

Goal

Problem statement

Proposed solution

Instructions for skins

In follow-ups to this task

Details

Related ObjectsSearch...

Event Timeline

Goal

Implementation

Standard variables

Devise a generic way for theme-agnostic stylesheets to adapt to the current theme
Closed, ResolvedPublic
Actions

Related Objects
Search...