Recommendations for night mode compatibility on Wikimedia wikis

Translate this page

Recommendations were made and are maintained by the Web team. They are based on data, technology trends, and our capabilities. As such, they evolve and may change.

Allowing users to switch between standard and night mode is a feature adopted across many websites, mobile devices, etc. It gives the user more control to make reading more comfortable. It is being added to our software as part of the Reading/Web/Accessibility for reading project.

Across Wikimedia wikis, there are efforts underway to introduce night mode in the user's preferences on the desktop and mobile sites. The Wikipedia apps for iOS and Android have already had these options for some time.

A significant road block to implementing night mode is how templates are constructed and styled. Another challenge is the usage of explicit colors, specified as inline CSS styles across various articles.

We can resolve these issues by raising awareness of night mode among editors, especially template editors. This is because templates can be included in many articles, and thus have a great impact for night mode compatibility.

The following are general recommendations and guidelines for editors to keep in mind when composing articles and templates.

How do I use different themes on MediaWiki?

For now, you can append ?minervanightmode=1 to the end of any URL to see how the content currently behaves in the night theme. You can also use https://test.m.wikipedia.org/wiki/Special:MobileOptions to enable night mode on our test wiki. We will update this instruction as the feature develops.

Recommendations

Use recommended HTML markup to describe your templates

Night mode will ship with styles that automatically fix known-universal problems with templates. This is important for projects with fewer technical editors. It will be possible to opt out of these styles by adding the notheme class to respective element or globally (phab:T358071). Projects that do not make use of these classes will likely get the feature later than others.

More information: Use standardized class names in HTML markup for components in templates across projects

Use accessible colors which pass WCAG AA checks

Many of the colors used in day mode have historically been inaccessible. When selecting colors for night mode, please be sure to check existing colors with the WebAIM contrast checker. Please consider modifying luminance to make the colors pass. Consider installing a browser extension such as the WCAG Color Contrast tool (Chrome, or Firefox) to get more awareness around the color contrasting issues on your wiki.

Bad example

@media screen {
	html.skin-theme-clientpref-night .element {
		background-color: #666666;
		color: #ace;
	}
}

Good example

@media screen {
	html.skin-theme-clientpref-night .element {
		background-color: #383838;
		color: #ace;
	}
}

Target night mode using standard media query as well as HTML classes

A standard readable skin-theme-clientpref-night class will be applied to the HTML element when dark mode has been enabled. However, styles that target night mode should also target prefers-color-scheme as certain users may have opted in via their operating system and subscribed to those styles via skin-theme-clientpref-os. Targeting prefers-color-scheme will style content appropriately for both sets of users.

Bad example

Template:Example/styles.css

html.skin-theme-clientpref-night .pane {
	background-color: white;
	color: black;
}

Good example

Template:Example/styles.css

/* forced night mode */
/* Note: If using a CSS variable, there is no need to make use of `@media screen` */
@media screen {
	html.skin-theme-clientpref-night .pane {
		background-color: black;
		color: white;
	}
}

@media screen and (prefers-color-scheme: dark) {
	/* automatic mode */
	html.skin-theme-clientpref-os .pane {
		background-color: black;
		color: white;
	}
}

Avoid static values for inline background and text colors

Numerous templates and articles make use of explicit inline colors, when they are not actually necessary. When building new templates, or reviewing existing templates, consider removing inline colors for the background or text. This will allow the current skin to apply its styles to all the elements automatically.

If you are browsing an article in night mode, and notice an element that seems to be clashing (e.g. a bright white table background), it is very likely due to an inline color specified for that element. Consider reviewing the article or template that is outputting that element, and removing the inline color.

If you believe that a certain element should have a specific color, consider looking for an appropriate CSS class (provided by the skin) that can be applied to the element, which would give it a more distinguishing color. If such a CSS class is not available, consider contacting the skin developers with a request to create a new CSS class.

Where you want to style things, it is recommended you use a stylesheet (see Help:TemplateStyles for more information) or a CSS variable.

Bad example

Template:Example

<div class="pane" style="background-color: white; color: black;">Text</div>

Good example

Template:Example

<templatestyles src="Template:Example/styles.css" />
<div class="pane">Text</div>

Template:Example/styles.css

@media screen {
	html.skin-theme-clientpref-night .pane { background-color: black; color: white; }
}
@media screen and (prefers-color-scheme: dark) {
	html.skin-theme-clientpref-os .pane { background-color: black; color: white; }
}

Always define color when defining background

When defining a background color, it may be tempting not to define the color if it is the same as the article text color. However, when different themes e.g. night mode are applied, this could have unintended consequences (e.g. white text on a yellow background). It is thus recommended that you always define the two together. A lint rule is provided to support editors to identify pages and templates with this issue.

Even if using CSS variables, it is important to explicitly define the color alongside the background to avoid assumptions about the context in which it is being used. For example, a template may be embedded inside another template / table that defines its own backgrounds or colors or there may be global styles applying to the page that may inadvertently impact your own content.

Bad example

Template:Example

<div style="background-color: yellow; padding: 16px;">Text</div>

Good example

Template:Example

<div style="background-color: yellow; color: #333; padding: 16px;">Text</div>

Use CSS variables or CSS design tokens with fallback for background and text where possible

Tracked in Phabricator
Task T360562
Resolved

Tracked in Phabricator
Task T361934
Resolved

Tracked in Phabricator
Task T368637
Open

Recommendation is currently restricted to use inside TemplateStyles (phab:T360562, phab:T361934).

CSS variables can only be defined inside gadgets and site CSS e.g. MediaWiki:Common.css.

When using design tokens you must note that stability is currently not guaranteed and may require later changes based on phab:T340477.

When using inline styles to modify text or background, let's use a CSS design token that is supported by the skin. A list of design tokens can be found in the Codex documentation. When using the CSS variables for Codex design tokens, always provide a fallback value for skins where CSS variables are not supported.

You can also define your own CSS variables inside a gadget (for example, the default hidden night mode gadget on English Wikivoyage).

Bad example

<span style="font-size:0.95em; font-size:95%; color: #54595d;">A subscription is required to read this URL.</div>

Good example

In this example, the color-subtle design token is used, with #54595d only used as a fallback when CSS variables are not available in the skin. This gives skins with night mode the information needed to adjust the content to a suitable color.

<!-- Always define a CSS fallback value for skins which do not support Codex e.g. Monobook. -->
<span style="font-size:95%; color:var(--color-subtle, #54595d);">A subscription is required to read this URL.</div>

Overriding night mode styles / disabling the night mode theme

In the current implementation of the Page Content Service (the service used by mobile apps to display articles), night mode works by overriding the colors of most elements with night styles, using the !important CSS property. This is precisely because of the large numbers of templates and elements that specify inline styles. In the web version, this also happens to a lesser extent (primarily on elements relating to infoboxes, navboxes and other common templates).

There may be cases where the color removal is unwarranted or where editors may disagree with the choice made. In such cases, you can include the notheme class in the element's style, which will prevent its color from being overridden (i.e. themed). This will result in the content being styled across themes (e.g. night/light/sepia) in exactly the same way.

Bad example

In this example, the theme will be overridden inside Wikimedia apps and any colors will be inverted in night mode on desktop or mobile web:

<div class="pane">Text</div>

Good example

In this example, the template has explicitly requested not to be overridden inside Wikimedia apps and the colors won't be inverted elsewhere:

<div class="pane notheme mw-no-invert">Text</div>

Apply filters to dark images with transparent background

Certain images (for example, signatures in infoboxes) tend to be black content with transparent backgrounds. In night mode, this results in unreadable SVGs because the black content will be on a dark background. To fix this, you can use a CSS invert filter (using the skin-invert or skin-invert-image class). When the thumbnail is accompanied by a caption you should use the skin-invert-image class to avoid inverting the caption as well.

Bad example

In this example this can result in a black inked signature on a black background

[[File:Tupac Shakur's signature.svg|thumb]]
[[File:Gas flare fr.svg|thumb|left|Éléments d'une torchère.|alt=Schéma. Le gaz est séparé du pétrole, déshumidifié, et envoyé vers la cheminée, il y a un allumeur au sommet.]]

Good example

Here the colors are inverted so the signature becomes white.

[[File:Tupac Shakur's signature.svg|thumb|class=skin-invert]]
[[File:Gas flare fr.svg|thumb|left|class=skin-invert-image|Éléments d'une torchère.|alt=Schéma. Le gaz est séparé du pétrole, déshumidifié, et envoyé vers la cheminée, il y a un allumeur au sommet.]]

For templates with no option to specify the class, you can use a <div> tag to wrap around the template and apply the class there. For example:

<div class="skin-invert-image">
    {{multiple image|align=center|total_width=540
        |image1=...
    }}
</div>

To invert all images in a gallery , you can add either the skin-invert or skin-invert-image class to the ‎<gallery> tag, depending on the context. (If your gallery uses captions, you should use skin-invert-image to avoid inverting the caption text.)

Gallery example

<gallery class="skin-invert-image">
Tupac Shakur's signature.svg
Gas flare fr.svg|Éléments d'une torchère.|alt=Schéma. Le gaz est séparé du pétrole, déshumidifié, et envoyé vers la cheminée, il y a un allumeur au sommet.
</gallery>

When `skin-invert` does not work

Certain images will not be easily invertible in night mode without losing important information (for instance, images with a dark base accompanied by bright colors). In these cases, the best option to preserve the image's original colors is probably to provide a light-colored background rather than invert the image, so that it can be seen in both day and night modes.

Avoid using `background: none` or `background: transparent`

Most of the time these are unnecessary, and worse still these will interfere with automatic fixes in place for night mode for your project. These should be removed or moved to TemplateStyles if absolutely necessary to avoid color contrasting issues in the night theme.

Bad example

<div style="background: transparent;">Text with transparent background</div>

Good example

The background rule is unnecessary.

<div>Text with transparent background</div>

Acceptable example

If the background is necessary, define color: inherit as well.

<div style="background: transparent; color: inherit;">Text with transparent background</div>

Advice for editors building alternative themes

More generally, we want to encourage editors to think of templates and articles as being agnostic with respect to theming and styles. In addition to night mode, there can be any number of potential color themes, and indeed the Wikipedia mobile apps (via the Page Content Service) already offer a "sepia" theme, as well as a "black" theme intended for power-saving OLED screens.

To invert or not to invert?

An invert using CSS filters provides a quick way to convert content designed in a light theme into a darker theme. While we cannot recommend this approach for all content , it is still a useful tool that can often be utilized safely and cheaply. The Wikipedia night mode gadget uses the invert CSS filter property to style content. You can prevent an element from having colors inverted by adding the mw-no-invert class. You can also use the skin-invert class to request that the content is inverted by the software when available.

Consider patterns rather than background colors

Colorblind readers can have difficulties telling apart and recognizing small colored items. In articles, consider using patterns rather than, or in addition to, color where appropriate. Ideally, where the pattern is separate from the text. Consider using monochrome CSS Background Patterns and reading about how Trello introduced a colorblind friendly mode.

Bad example

Template:Example/styles.css

html.skin-theme-clientpref-night .ib-youtube-above {
	background-color: #B60000;
	color: white;
}

Good example

Template:Example/styles.css

@media screen {
	html.skin-theme-clientpref-night .ib-youtube-above {
		background-image: linear-gradient(135deg, #ff1c00 25%, transparent 25%), linear-gradient(225deg, #ff1c00 25%, transparent 25%), linear-gradient(45deg, #ff1c00 25%, transparent 25%), linear-gradient(315deg, #ff1c00 25%, var(--background-color-base) 25%);
		background-position: 8px 0, 8px 0, 0 0, 0 0;
		background-size: 8px 8px;
		background-repeat: repeat-x;
	}
}

Why are links black in colored tables

It is quite common for editors to create tables with background colors defined on rows or columns. If the table contains links this can be problematic, as often the color choices will be tailored towards accessibility in the standard theme, or will not consider accessibility at all.

For example the links in this table are accessible in light theme but not the dark theme:


Phab ticket	Description
T360844	Links in elements with background color should become black with an underline so they are accessible
T357575	File pages are not compatible with night mode

Instead of blue links inside these tables, such links will appear as black. If this behaviour is not wanted, please revise your tables to not use inline styles.

More information in phab:T371411.

Note this behaviour only applies to article namespace. If you are using a table with different colored rows in another namespace, you should consider creating a template that provides support for making links pass WCAG AA color contrast standards. You can use Extension:TemplateStyles to style links appropriately.

Disabled text does not necessarily need to meet color contrast guidelines

From https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html

User Interface Components that are not available for user interaction (e.g., a disabled control in HTML) are not required to meet contrast requirements. An inactive user interface component is visible but not currently operable. An example would be a submit button at the bottom of a form that is visible but cannot be activated until all the required fields in the form are completed.

The page looks fine to me, despite not following these rules, why?

To reduce the amount of initial work that is required for wikis to adopt night mode, various generalized solutions may have been applied for the time being to pages to help them comply with night mode. These styles will eventually be removed, when wikis have adapted to the new theme.

These are listed here:

WikimediaMessages SiteAdminHelper - the site admin helper ships various styles that improve night mode support - this includes disabling/updating backgrounds and borders in elements with the class .navbox, .infobox, .quotebox, .side-box, .metadata, .navigation-box, and all elements on the main page. It also enforces black text color on any element which defines an inline style with a background rule. Note, while this fixes the large majority of issues, this also causes breakage to some elements, in particular any style attribute that sets background: inherit and background: transparent.
MediaWiki:Vector-2022.css / MediaWiki:Minerva.css rules - some wikis may have adopted generalized rules that change links to black underlined text to any table element that have inline styles that apply backgrounds. For example English Wikipedia.
A local solution may have already been applied to the template you are looking at. Be sure to inspect the element and look at any associated styles provided by template styles that may be applying specific rules when the night theme classes are detected on the HTML element.

Examples

The following tickets explain fixes for various namespaces/templates and types of pages that were applied to a single project. They may be useful to other projects with similar templates or outdated copies of those templates.

Please be sure to read the associated discussion – and ask questions if you have any so other projects can benefit from sharing expertise.

General issues

Links inside table rows with background colors: phab:T360844
Tables with alternating row colors T358003
Transparent SVGs in infoboxes Example fix

Portals

Portal:Current events T357717

Templates / modules

Template:Color T360683
Module:Track listing T357730
Module:Citation https://phabricator.wikimedia.org/T359894
Template:No_article_text https://test.wikipedia.org/w/index.php?title=Template%3ANo_article_text&diff=596846&oldid=494808
Module:Message_box https://test.wikipedia.org/w/index.php?title=Module%3AMessage_box&diff=596845&oldid=579405
Licensing templates:
- Template:PD-self https://test.wikipedia.org/wiki/Template:PD-self
Template:Key press

Messages

Please review the following messages on your wiki:

Recommendations for night mode compatibility on Wikimedia wikis

How do I use different themes on MediaWiki?

Recommendations

Use recommended HTML markup to describe your templates

Use accessible colors which pass WCAG AA checks

Target night mode using standard media query as well as HTML classes

Avoid static values for inline background and text colors

Always define color when defining background

Use CSS variables or CSS design tokens with fallback for background and text where possible

Overriding night mode styles / disabling the night mode theme

Apply filters to dark images with transparent background

When skin-invert does not work

Avoid using background: none or background: transparent

Advice for editors building alternative themes

To invert or not to invert?

Consider patterns rather than background colors

Why are links black in colored tables

Disabled text does not necessarily need to meet color contrast guidelines

The page looks fine to me, despite not following these rules, why?

Examples

General issues

Portals

Templates / modules

Messages

When `skin-invert` does not work

Avoid using `background: none` or `background: transparent`