Recommendations for night mode compatibility on Wikimedia wikis

See also: Recommendations for mobile friendly articles on Wikimedia wikis

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.

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 to get more awareness around the color contrasting issues on your wiki.

Bad example

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

Good example

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 */
html.skin-theme-clientpref-night .pane {
      background-color: black;
      color: white;
}
@media (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

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

Always define color when defining background if not using CSS variables

If using CSS variables per this guideline this guideline can be safely ignored.

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.

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

Recommendation is currently restricted to use without fallback for use inside TemplateStyles ( phab:T360562, phab:T361934). In the mean time you can define and use tokens inside inline styles, 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 either use a CSS invert filter (using the skin-invert class) or apply a background color of white to the image.

Bad example

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

[[File:Tupac Shakur's signature.svg|thumb]]

Good example

Here the colors are inverted so the signature becomes white.

[[File:Tupac Shakur's signature.svg|thumb|class=skin-invert]]

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

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;
}

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.

Portals

• Portal:Current events T357717

Templates

• Template:Color T360683