Help:Lint errors/night-mode-unaware-background-color

While this lint is designed to improve Wikipedia's night mode, it is really about ensuring our content is portable and can be rendered in contexts other than a Wikipedia article. Understanding the false positives that this lint may cause, assistance remains available on the project talk page (see below) and suggestions are welcome. While some lints logged under night-mode-unaware-background-color in the Wikipedia night theme may appear unnecessary and already meet WCAG color contrast rules, it remains vital to pinpoint them, as a significant number are likely problems in other contexts where people consume our knowledge.

This documentation outlines the specifications and usage guidelines for the "night-mode-unaware-background-color" linter, a tool designed to assist in identifying potential issues related to background colors when Wikimedia content is used outside the default experience e.g. in a night theme environment or when rendered by the Wikipedia app or embedded in another site which may use color schemes other than our own. It is important to note that this lint is currently in the analysis stage and editors are not expected to take immediate action based on its findings.

Overview

The "night-mode-unaware-background-color" linter is designed to detect certain instances where background colors assume a certain text color, and may not be suitable for a night mode environment amongst other environments. This lint specifically targets most inline background colors that lack an accompanying color inline style within the same tag.

Its primary objective is to ensure that background colors meet accessibility standards, particularly in terms of color contrast, as outlined by the WCAG 3:1 standard, via explicit color definitions other than making assumptions about how the page will be rendered.

How to fix

Quick start

In most cases problematic styles will be highlighted in the editor. Where this is the case adding a color rule–e.g. inherit or black–will address the issue.

This table explains what colors to use and under what circumstances
Background	Color to use	Note
background: transparent or background: inherit	`color: var( --color-base );`	For information on CSS variables see this section of our recommendations. In some cases, you may find color: inherit may be more appropriate, for example in complex tables where backgrounds may be defined on other parent elements such as TR or TBODY element but you should usually default to the design token.
Light color background	`color: black;`	If using a light background e.g. white, it's important to mark up the content so that it knows it should not rely on the default text color.
any background where inherited text defines a color	`color: inherit;`	If the text itself is captured by its own color declaration like in this example below, use of `color: inherit;` is recommended. <span style="background: purple;"> <span class="color: white;">white text</span></span>

Previously, it was safe to define a background using an inline style as we could assume that the default text color was always black, but this has never been true for sites or apps which reuse our content, and as MediaWiki adds support for native themes such as dark mode, this is no longer the case for Wikimedia sites either. These native themes may alter colors where a background is detected without a color.

We therefore recommend always defining a text color alongside a background color per the guidelines on our recommendations page.

Examples
Problematic HTML	Good HTML
<span style="background: white;">This is meant to be black text on white background in day theme! We are assuming the text color of the rendering is always going to be black since it has been that way since Wikipedia was invented. But now.. it's white text on white background in night theme so we must specify the color.</span>	<span style="background: white; color: black;">This is meant to be black text on white background in day theme! We are assuming the text color of the rendering is always going to be black since it has been that way since Wikipedia was invented. But now.. it's white text on white background in night theme so we must specify the color.</span>
<span style="background: red;">This is black text on red background!</span>	<span style="background: red; color: black;">This is black text on red background!</span>
<span style="background: red;"> <!-- if text is ever added it here it is //implied// that it will inherit from the stylesheet but this has not been made explicit-->hello. <span style="color: yellow;">I am yellow text!</span> </span>	<span style="background: red; color: inherit;"> <!-- The color: inherit has clarified what the behaviour should be here --> hello. <span style="color: yellow;">I am yellow text!</span> </span>
<span style="background: red; color: yellow;">Foo <span style="background: blue;"> <!-- while it is implied from the context the color of this text will be yellow it is not clear if that is deliberate or a mistake (perhaps the parent is from another template that recently changed Night themes will convert this to black unless specified.--></span></span>	<span style="background: red; color: yellow;">Foo <span style="background: blue; color: inherit;">bar</span></span>

Advanced: Troubleshooting templates

For HTML generated by templates further debugging may be required. It is recommended you add the following code to your user JS to help debugging issues:

// make it obvious where things are broken by disabling the auto-correction fix.
mw.util.addCSS(`html.skin-theme-clientpref-night body .mw-parser-output [style*='background'] {color: inherit; }`);
// add a border around issues.
$('[style*="background"]:not([style*=";color"]):not([style*=" color"]):not([style^="color"])').css('border', 'dotted 5px red')

For any elements that match the above selector, update the template to add the following code to the associated style attribute:

<!-- for Lua templates  -->
<!--  :css('color', '#202122') -->

<!-- For inline HTML prepend color to existing style attributes. -->
<div style="color: #202122; background ..."></div>

After locating the associated template and making the change, go to the page flagged on Special:LintErrors and add ?action=purge to the URL to purge it. The entry should disappear from Special:LintErrors if it has been fixed. If it hasn't there may be other templates associated.

Example:

Identifying problematic elements

The following JavaScript code will help identify elements in the page that trigger the lint.

Array.from($('[style*="background"]')).filter((a)=>!a.style.color)

Why are we fixing this?

As you can see there are a large number of issues flagged by the linter. We temporarily added CSS rules to the WikimediaMessages extension to mitigate the urgency on fixing these, however there are some downsides:

Sometimes the CSS in WikimediaMessages doesn't work as expected and negatively impacts the page
The WikimediaMessages extension uses computationally expensive CSS selectors such as :not and contains (*=).
Since WikimediaMessages needs to apply rules that work on all wikis, some are irrelevant or problematic in certain wikis.
The styles in WikimediaMessages are loaded on all pages.
Makes debugging issues harder, as editors have to understand where unexpected CSS rules are coming from.
The fixes only apply when content is consumed on Wikimedia sites.

The latter is arguably the biggest concern here - given the Wikimedia Foundation mission we want to disseminate our information effectively and globally, and this includes being able to embed snippets of content in contexts where the background color is not white and the text is not black. In addition to this, we want to ensure that color is used in a way that makes content accessible. By marking up content in this way, we are empowering tools of the future to be able to detect color contrast issues and report them to future editors.

Current status

The "night-mode-unaware-background-color" lint is assigned a priority level of low as while dark mode is being rolled out to all wikis, dark mode has some workarounds in place to address what we estimate it around 80% of the issues listed by this lint.

Following analysis to determine the validity and impact of its findings and concerns raised by the community the priority of this lint was raised to low.

We encourage communities to review the problems flagged by template transclusion of comment templates to identify and address common issues with the night theme.

Usage guidelines

While editors are not required to take action on the lint findings at this time, those who wish to contribute to address potential issues can follow these guidelines:

Review Lints: Editors can review the lints generated by the "night-mode-unaware-background-color" linter rule to identify instances where inline background colors lack a color inline style. Note that some instances may be transcluded via templates.
Ensure Color Contrast: Verify that background colors meet the color contrast criteria outlined by the WCAG 3:1 standard. Editors can use tools such as WebAIM: Contrast Checker to check if their color styles adhere to these standards.
Inspect Pages: Use plugins such as the WCAG Color Contrast Checker Chrome Plugin to inspect pages and ensure that content complies with WCAG color contrast criteria, particularly for elements that you are responsible for.
Communicate Concerns: If you have any questions or concerns regarding the lint or its findings, we encourage you to leave comments on the project talk page and clarification.