Requests for comment/Themes in core

This is a proposal to merge the Theme extension into MediaWiki core as built-in functionality that skins can implement in a simple and consistent manner, enabling user- or site-selection of css variations of a given skin, such as a dark version or a layout with more colours.

Request for comment (RFC)
Themes in core
Component Frontend
Creation date
Author(s) Isarra
Document status
See Phabricator.

The linked task discusses the technical details of this, as well as how we intend to follow up in order to fully support proper variable-based themes and SkinStyles modules; please comment there.



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

Themes: Variants of a skin in terms of colours, fonts, simple layout changes; specific to a given skin

  • Theme examples: Night mode versions of skins, simplified layouts, different colours on the same general page structure (such as the original green, blue, red, and white versions of BlueSky, and various branded skins for third-party projects). There are many live examples on ShoutWiki:
  • Implemented by Extension:Theme to allow skins to specify alternate stylesheets that load over, or instead, of the default stylesheets for the skin

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.

Expressed or demonstrated demand for theme functionality:



The longstanding desire for this functionality and the problems with the existing skinning system have resulted in several issues:

  1. Fragmentation of implementation methods:
    • Skin developers may not want to depend on a separate extension, and roll their own solutions (sometimes based on the extension, sometimes not)
    • no standard approach, so not standard way to fix/update them as core changes - maintenance 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?
  2. 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)
  3. 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 it.

  • stuff like'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 platform, "just" the users of that one site. For ones like this, 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 forward, this should not require an all-out restyle in Skin.css, either. Needs to be easier for the users to do in the first place.


  1. Merge Extension:Theme into core
  2. Migrate toward simpler skin handling from there, once we have consistent basic backend/core support. per task T122924

Current Theme functionality is as follows:

  • 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.
  • Create onwiki interfaces for site admins to create their own themes to customise the site.
  • 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.)

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.


  • That this could cause skin options to explode: more to test against, more common configurations that developers need to not break.
    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.


  • 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...
  • 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.