This is a proposal to merge the [[https://www.mediawiki.org/wiki/Extension:Theme|Theme extension]] into MediaWiki core as built-in functionality that [[in order to generally make it a lot more effective and useful. For a more thorough background on what MediaWiki themes are and the context for their use, please see the [writeup on mw.org](https://www.mediawiki.org/wiki/Manual:Skins|skins]] can implement in a simple and consistent mannerRequests_for_comment/Themes_in_core). This task describes the technical aspects, enabling user- or site-selection of css variations of a given skin,on the assumption we can all agree that we want to support things like Night mode and accessibility options in a way that doesn't constantly break and isn't purely js-based and/or done by adding a bunch of extra css on top of the existing styles. such as a dark version or a layout(//Does// anyone disagree with more colours.that?)
# Background
The terms 'skin' and 'theme' are often used interchangeably, as different products will tend toward one or the other for the same general purpose - a specific styling of the user interface/layout for the product. While these both hold true for MediaWiki as well, 'skins' and 'themes' are each specific things within this context:
Skins: MediaWiki extensions implementing the overall page, including general layout and placement of content and tools, in order to construct and output the final html, css, and js that visitors receive== Problem ==
* Consist of registration, a php class, the html output, and non-content js and css styles
* Examples: [[https://www.mediawiki.org/wiki/Skin:MonoBook|MonoBook]], [[https://www.mediawiki.org/wiki/Skin:Vector|Vector]]Extension:Theme|Extension:Theme]] enables setting different variants (typically colour schemes, [[https://www.mediawiki.org/wiki/Skin:Minerva_Neue|Minerva]]such as Night mode or the official colours of a project) for skins, and represents the most effective, [[https://www.mediawiki.org/wiki/Skin:Timeless|Timeless]]efficient extant implementation we have for such functionality (the above writeup on mw.org includes many links to less effective implementations).
Themes: Variants of a skin in terms of colours, fontsAs an extension, simple layout changes;however, specific to a given skinit has certain limitations:
* Consist of css and/or a set of LESS variables to override or replace a skin's default styles* All we can really do is define new modules, typically to add stylesheets on top of the existing stylesheets.
* Examples: Night mode versions of skins, simplified layouts, different colours on the same general page structure (such as the original green, blue, redWe can't feasibly use SkinStyles (loading component-specific styles only on page(s) the components are on) extending ResourceLoader itself to handle themes, and white versions of [[https://www.mediawiki.org/wiki/Skin:BlueSky|BlueSky]])so we basically just have to load all theme styles on all pages.
* Implemented by [[https://www.mediawiki.org/wiki/Extension:Theme|Extension:Theme]] to allow skins to specify alternate stylesheets that load overWhile it is technically possible to create variable-based themes, it's super hacky and basically just requires //including// all the actual styles from the variables files, instead of visa versa. And any theme variables again cannot be reused in SkinStyles.
* Developers tend to be resistant to making their products //depend// on other products, and we've already wound up with a bunch of half-forks, or insteadgenerally out of date and incomplete, of the default stylesheets forextension living in various skins so that they don't require deploying an extra extension to make use of the skinfull features.
Skins a built-in specified part of MediaWiki core, and so are relatively consistent and straight forward, but themes are currently only implemented in a third-party extension and (inconsistently) in a few specific skins. Because of this, we see repeated requests for use of the functionality both on larger projects like Wikimedia and among smaller third-party projects, but for the most part little comes of it. What implementations we have seen are varied and scattered.== Solution ==
Expressed or demonstrated demand for theme functionality:We should be moving toward using variable-based themes, as this is both more efficient to render and download, and also a lot easier to actually //make// as a developer. Because of the widespread desire for theme support and that some of this requires changing how ResourceLoader handles skin modules, it is simply not feasible to continue to support this in an extension.
* Wishlist items:
** [[https://meta.wikimedia.org/wiki/Community_Wishlist_Survey_2019/Reading/Night_mode|meta:Community Wishlist Survey 2019/Reading/Night mode]],
** [[https://meta.wikimedia.org/wiki/Community_Wishlist_Survey_2017/Reading/Night-mode_for_read_articles%3F|meta:Community Wishlist Survey 2017/Reading/Night-mode for read articles]]?,
** [[https://metaI propose three things:
### 1. Merge the current logic of Extension:Theme into core ([[https://gerrit.wikimedia.org/wiki/Community_Wishlist_Survey_2019/Reading/Accessibility_settings_for_everyone|m:Community Wishlist Survey 2019/Reading/Accessibility settings for everyone]],
** others?
* Gadgets and user styles onwiki implementing various style changes to specific skins:
** [[https://www.mediawiki.org/wiki/Skin:Vector-DarkCSS|Skin:Vector-DarkCSS]]
** [[https://www.mediawiki.org/wiki/Skin:Grey_Vector|Skin:Grey Vector]] etc,
** [[https://www.mediawiki.org/wiki/Skin:Timeless-DarkCSS|Skin:Timeless-DarkCSS]],
** that green-black enwp gadget
* Third-party projects customising common skins like Vector/MonoBook:r/c/mediawiki/core/+/465451|patch]])
This does the following:
* Add the basic support for defining the themes a skin supports (adding ThemeModules)
** [[https://www.mediawiki.org/wiki/Skin:Eveskin|EVElopedia]] (monobook fork with redone css),* Enable the settings for users/sysadmins to select themes, the ?usetheme url param for testing, etc
** Zelda wiki (Vector CSS override using Theme extension),* Add the basic logic of adding theme modules, which will be loaded along with the other default modules (currently this is all the extension does and isn't a good solution in general, but we will still need this even with proper variable support regardless - sometimes, you gotta override/add some extra styles for a particular theme to fully work, no matter how good your variables are)
### 2. Add support to ResourceLoader to handle skin modules and theme modules together
Allow ResourceModule definitions to define what theme(s) their styles are for, and only use those styles if on that theme. Any styles where this is not set will be assumed to be for all themes. Same thing for adding to ResourceModuleSkinStyles - support adding to a module, but only for the given theme for the given skin.
So one might define a module like so:
```
** Darthipedia (was CSS over the MonoBook "skins.skin in MonoBook.css + some other stylesheets),withnighttheme": {
** GW2wiki (CSS changes to Vector and MonoBook via MonoBook.css, Vector.css "targets": [ "desktop", Common.css)"mobile" ],
** and other thematic and game wikis in particular) "styles": {
* Forks of Vector/MonoBook where all they're really changing is the css (one of the most common ways to create a new skin) "resources/main.css": {
* External tools such as WikiWand, Winter, others "media": "screen"
* According to https://etherpad.wikimedia.org/p/WikiDev16-skinning, this seems to be wanted.
# Problem },
The longstanding desire for this functionality and the problems with the existing skinning system have resulted in several issues:
# Fragmentation of implementation methods: "resources/main-night.css": {
* Skin developers may not want to depend on a separate extension, and roll their own solutions (sometimes based on the extension, sometimes not) "media": "screen",
* no standard approach, so not standard way to fix/update "them as core changes - maintenance e": "nightmare"
* Even if the solution built-into the skin is initially based on and compatible with the Theme extension, still a maintenance nightmare as they fall out of date },
* caching issues in different implementations? ashley please comment, does ext:theme have problems with this? ...
# difficult to implement due to having to install extra things for support and/or start from scratch: }
* developer solutions tend toward front-end JS- and CSS-only overrides instead of working with some of the newer, cleaner technologies (such as LESS variables)},
# override approaches are inconsistent; need a consistent approach defined in the first place to head toward cleaner solutions (defining colours/variables instead of overriding them to determine skin behaviour)```
We don't even know about most of the variants floating around, customised wikis that do a change and then we never hear back about ithere the main-night.css is loaded after the main.css as part of the same module iff the night theme is selected.
* stuff like ZeldaWiki.org's default color scheme (aka the "dark" theme for both MonoBook and Vector) -- born out of a certain necessity, made for a certain site but not necessarily targeting the wider MW platformThis would be //doing// effectively the same thing as Theme does currently, "just" the users of that one sitebut more cleanly. For ones like thisHowever, such a significant desk and development undertaking that it's precisely the kind of thing we want to shed light on and perhaps even get those developers to participate in the wider community (="new developers" buzzword and all that jazz)
* Going forwardchanging to this approach will break backwards compatibility in terms of how we define themes and their stylesheets (currently we create separate modules entirely for each theme, this should not require an all-out restyle in Skin.csswhich will no longer be necessary as such), either.so all current skins supporting themes will need to be updated, Needs to be easier for the userswhich we plan to do in the first placeconcurrently.
# ProposalAgain, this will still be required even after adding #3, as not all themes will be possible by (only) changing variables. For instance, one might make a theme to change all the fonts to be bigger, higher contrast, etc: while the main part would be done by changing the fonts and font-sizes in the variables file, it will likely also require adjusting/specifying some other changes as well to fully work, such as line heights, paddings and border positions for certain interface elements, and things like that that cannot necessarily be set/calculated from the variables themselves.
# Merge Extension:Theme's logic into core, and keep any existing themes not being merged into the skins themselves in the extension,## 3. repurposing it as a compilation of the legacyAdd explicit support for themes.
# Migrate toward simpler skin handling from theree variables, once we have consistent basic backend/core support.and push it as the primary method of implementing a theme
https://gerrit.wikimedia.org/r/c/mediawiki/core/+/465451/ per task T122924Basically, we add some way such that when we import the skin's default variables.less file, we can also import the automatically determined current theme-variables file.
## Current Theme functionality is as follows:So perhaps we do
* Enable skins to specify alternate stylesheets to load depending on the theme selected (each theme functions as an RL module tied to the name of the theme). These can be loaded over general CSS or instead. Preferred implementation is of course to keep it all as simple as possible and avoid using the theme as an override, and instead contain only the relevant styles for the theme, but this does not preclude developers making a mess of things regardless.```
* Add settings (site and user) for each theme, displayed for users in their preferences when they enable the skin the themes pertain to.
Merging this into core will allow us to then iterate from there:
* Create a core framework for setting skin variables which will then automatically load into the rest of the skin (or perhaps even core) less."ThemeModules": {
* Create onwiki interfaces for site admins to create their own themes to customise the site. "skinwithnighttheme": [
* Enable skin creators to create css-only skins, reusing existing skins' code without having to worry about maintenance by creating only the RL modules? (No more vector/monobook forks in order to only redo the css.) "night": {
We may need to come up with guidelines as to what canned themes skins generally come with - perhaps keep it to only three or so, a light, a dark, and optionally some sort of colourful version, where from there site admins have reasonable examples from which to create their own with the specific colours they actually want.
## Concerns
* That this could cause skin options to explode: more to test against, more common configurations that developers need to not break. "variables": "resources/themes/night.less"
** There are already infinite things wikis can do with their own styles/gadgets/whatever, so this, if anything, should help clean that up by providing more consistent predictable options to test against, and putting all the options more in the same place... },
** Pandora's box has already been opened, long, long ago. See below ([[#Precedent]]) ...
* About the addition of more preference items: general concern about too many options causing issues for users, for database management, whatever. ]
** From a UX standpoint it should be fine as new options will only be shown for the active skin. Is actually an improvement over status quo as we are more likely to have more inconsistent skin settings at present, and this should help standardise where and how they appear (won't be elsewhere under #Appearance, won't have themes floating around #Gadgets)...},
** DBA-side, should be relatively negligible.```
## Precedentin the skin.json, and this gets passed into a less variable we then use to load the file with the variables:
* Basically like allowing mw to have extensions and skins in the first place, where the benefit of those is a simpler, more consistent implementation of what is/was already out there; likewise these are also already out there, so a single standard in core keeps them consistent and simplifies the lot.```
* MediaWiki:Skin.css, $wgAllowUserCss (and $wgAllowUserJs) are things and have been things for a long time and as long as they've been things users have created custom CSS color schemes and stuff and shared 'em and now we want them to become somewhat standardized and maintained...@import resources/variables.less // or whatever we called the main one
* [[https://www.mediawiki.org/wiki/Extension:Gadgets|Extension:Gadgets]] can be used to implement this wiki-side, but likewise has issues with code review/maintenance across projects. These are more specific (specific to a skin, in fact), so we're proposing to use git/gerrit for skins' themes in the skin repositories, which is both neater in terms of UX (skin-related stuff showing up with specific skin as opposed to in massive list of usually skin-agnostic gadgets) and review/maintenance/development.
-----@import @theme-variables;
```
This task now an RfC to merge a patchSo then any variables in the second one override the first, because People Were Concerned.but it doesn't require the second having all of them, For a full overview of why we want to do this,either. including the background of themesAnd if no theme is selected or the theme doesn't actually have any variables (who knows, skins,maybe one of the themes just rotates the entire page upside down or something; and what all that meansyou don't need variables for that), please see the [writeup on mw.org](https://www.mediawiki.org/wiki/Requests_for_comment/Themes_in_core)just send it an empty file for the second.
# What we're proposing is this:== Notes ==
# **Merging the linked patch to merge Extension:Theme into core.** Under wider review,If none of this makes sense, please look at how current skins define ResourceModules (example: any), ThemeModules (example: Bouquet), and ResourceModuleSkinStyles (example: MonoBook) in their skin.json; and tend to import a variables.less file in their specific stylesheets (example: Timeless).
# The suggestions for #2 and #3 are generally based on what we currently define in skin.json etc and what we could probably do with a ResourceLoaderVariableModule, but are largely theoretical. The Theme extension itself, however, already exists and is mostly solid in terms of what it's doing; do we have consensus (or at least no objections)?it's just not doing //nearly enough//.
# The original RfC can be found [on mw.org](https://www.mediawiki.org/wiki/Requests_for_comment/Themes_in_core). Does anything need changing?Some discussion has also occurred on the related [talk page](https://www.mediawiki.org/wiki/Talk:Requests_for_comment/Themes_in_core) onwiki.
# We're also a bit fuzzy at this point what we actually intend next, so further discussion of //that// is probably very much in order here as well. That, or we can just worry about that later when someone has more time/some actual resources to do... whatever it is. At least putting //this much// in core means we'll have much more consistent handling across skins regardless of what we do next, as they will not longer need to depend on the extension or roll their own.
Some discussion has also occurred on the related [talk page](https://www.mediawiki.org/wiki/Talk:Requests_for_comment/Themes_in_core) onwiki, but let's continue future discussion here for consistency, as this was the original task for the patch, and phabricator is just less annoying in general.