How the page is darkened#

Automatic (recommended) is the one to use. Every stylesheet on the page is read and re-coloured, which is why it works on a theme nobody has ever seen: photographs stay photographs, a coloured button stays that colour but darker, and text stays legible against whatever is behind it. It is about 39KB over the wire, fetched whenever a page is shown dark. It is also the heaviest of the methods on the reader's device: measured, about 155 ms of extra work per dark page on a desktop and about 475 ms on a mid-range phone, where Invert and Basic add next to nothing.

Invert colours is one CSS filter over everything. It costs nothing and runs anywhere, and it inverts pictures — corrected for anything in an <img>, and impossible to correct for a picture set as a CSS background. Suits a text site; on anything with a photographic header it will look wrong.

Basic (no JavaScript) writes your four colours into the page and stops. No JavaScript at all after load, and no cleverness: it sets the page, the type, the links, the form controls, the buttons and the tables, and leaves anything it cannot know about alone. The fastest of the three and the least faithful on a complicated theme.

Faithful is the right word for what it gives up. A theme prints colours of its own on its navigation, its prices, its comment text and its footer credit, and panels of its own behind cards and table rows — all of them chosen for a white page. This method overrides those, because a tinted panel it cannot see through is not "less faithful", it is a paragraph nobody can read. Your theme's tinted boxes are the price; on a complicated theme, use Automatic instead.

Your theme's own dark style appears as a fourth choice when your theme is a block theme that comes with a dark style of its own, as Twenty Twenty-Five does with Evening, Twilight, Sunrise and Midnight. Choose it, then pick one of the styles shown below it, each drawn in its own background, text and first accent with how well its text reads. No script is downloaded for it.

While a page is dark, the plugin applies the style's colours:

your theme's palette is swapped for the style's, so everything your theme colours from its palette, and every block you gave one of its colours, takes the style's colour;
the page's background and text become the style's;
the colours the style gives links, buttons, headings and blocks, and the colours it gives your theme's section styles (the Style 1 to Style 5 groups in Twenty Twenty-Five), are applied too, so a section keeps readable text on its background as it does when you pick the style in the Site Editor.

Only colours are taken from the style. Its fonts, spacing and other design changes are not, so your pages keep their shape and only their colours change.

The plugin offers a style only when it is dark and readable once applied: its page background is dark, its text reads at 4.5:1 or better, and so do the text of each of your theme's section styles and the links and buttons on the page and in each section. A style that fails any of these is not offered.

On WordPress 6.5 and earlier, section styles have no colours of their own, so the plugin does not apply or check them there.

What it does not change:

A colour typed into a block as a fixed value, rather than picked from your theme's colours, stays as it is. Choose one of the theme's colours for it in the editor, or add a rule under Advanced → Custom CSS.
Colours you set for one block in the editor, such as a link colour on one paragraph, keep your choice, as they do in the Site Editor.
Another plugin's own colours, and anything your theme styles without its palette.
Colour Scheme and Fine-Tuning do not apply, since the colours are the style's. Images and Elements hides its lists of parts to leave alone or to invert, which have nothing to work on here; they are kept for the other methods. The dark logo, the image pairs and image dimming still apply, and so does your Custom CSS.

The style belongs to the theme it was chosen on. Switch to another theme and the pages are darkened with Automatic until you choose again: the Colours screen and the Dashboard say why, and the Colours screen leaves the new theme's styles unticked, so saving it for another reason does not choose one for you. On a theme with no dark style of its own, such as a classic theme, the Colours screen shows Automatic ticked, since that is what the pages get, and you can still adjust its colours there. Saving the screen keeps the dark style you chose, and the note under the method names the theme it is kept for. To use Invert colours or Basic instead, select it and save. To make Automatic the method for good, select it again before you save, or choose it after you switch back. Switch back and the style you chose is used again. A classic theme never shows the choice. When your theme has a dark style and another method is in use, the Dashboard's Recommended card suggests it, after anything that needs fixing first, such as a missing dark logo; it never changes the method by itself.

The palette#

Twelve to start from — Ink, Slate, True black, Warm, Midnight, Forest, Plum, Ocean, Charcoal, Frost, Layers and Bold. Every one was checked for contrast before it shipped, so choosing one and changing nothing gives you a page people can read.

Ten of them are the same shape in different colours: a page, its type, and a hairline where a rule belongs. Ink is near-black with warm off-white text and suits most themes. Slate is cool blue-grey and Frost a calmer steel blue-grey; Midnight is navy, Forest green-black, Ocean teal-black and Plum aubergine-black, for a site whose brand is that colour rather than blue. Warm is brown-black with amber text for reading at night. True black saves battery on an OLED screen; Charcoal goes the other way, a softer dark grey for anybody who finds near-black too stark. Two are a shape as well as a colour.

Layers is warm graphite, and it draws with panels instead of lines. A quote, a code block, a picture and a table each sit on a rounded panel a step above the page, a table is read by its alternating steps rather than by gridlines, and there is no rule anywhere except the edge of a form field, which keeps one because you have to be able to find it.

Bold is the opposite and is meant for low vision and for bright rooms: pure black, white text at 21:1, nothing faint anywhere — captions included — square corners, two-pixel rules through and around tables, around a code block and around a word of code in a sentence, a framed picture, buttons and form fields as two-pixel outlines, and links in running text underlined so colour is not the only thing marking them. Your theme's own menus keep their usual look.

Both draw their shape under Automatic and Basic. Invert does not use the palette at all, so it does not use these either.

Under them are the four colours themselves. They start as the palette you picked; change any and the change is yours to keep, until you pick a different palette, which brings its own four. The preview beside them shows the numbers: 4.5:1 is the line for body text, and the preview says so rather than leaving you to guess. Under Automatic the preview and its figure include Fine-Tuning, because the engine applies it to the palette too. The engine also deepens the page a little on its own, so a visitor's page comes out slightly darker than the preview: Ink #14161A shows as about #101215.

Which of the four a method uses differs. Automatic takes the background and the text; links and borders keep your theme's own colours, darkened by the engine, so the Links and Borders pickers are greyed there (the link colour is only used if the engine cannot load). Basic uses all four exactly as picked. Invert uses none of them.

Seeing it on your own pages#

Preview on site, at the top of the Colours screen, opens your home page dark with the settings you have saved. It is a look, not a choice: nothing is remembered in your browser, so the next page you open, and your schedule and device setting, carry on exactly as your visitors get them. It shows only to people who can change these settings, and it is not offered while dark mode is switched off. Save first — the preview shows what is saved, not what is still in the form.

The browser's own bar#

On Android, Chrome and Samsung Internet colour the bar above the page from the page itself, and so does a site installed as an app on a computer. While a page is dark that bar is dark too, in the colour the page is painted with: the palette's background, your theme's dark style's own, or under Invert the page as it comes out inverted, Fine tuning included. A reader who chose dark gets it from the first paint. When the page goes light the bar takes your theme's colour again, or the browser's own where your theme sets none. A reader who leaves the page light gets nothing extra, and there is nothing to set.

The parts the browser draws itself, such as scrollbars and plain form fields, are dark while the page is, except under Invert, which turns over a light page rather than drawing a dark one.

Fixing a part on the page itself#

Every exception on Images and Elements can be made by clicking the part that looks wrong, instead of typing a selector.

Signed in as an administrator, open any page of your site that dark mode applies to and choose Fix dark mode here in the black toolbar (on a phone it is an icon there). The Colours screen has the same link for your home page, Fix dark mode on site, beside Preview on site. The page opens dark, the way Preview on site opens it: nothing is remembered in your browser.

If dark mode is off on the page you opened (Display Rules leave it out, or the page's own setting does), the toolbar says Dark mode is off on this page and links to Display Rules. At a screen size Display Rules leave out, the bar at the bottom says so instead of starting to pick.

Point at the part: it is outlined. Click it, and a small panel says how it will be named (a CSS selector, such as span.badge) and how many things on the page that matches, so you can see before saving whether it catches more than you meant. Pick the part around it moves to the element it sits in, for when a click lands on the words inside a badge rather than the badge. Then choose:

Keep its own colours adds it to Parts of the page to leave alone.
Invert it adds it to Parts of the page to invert.
Use a dark version, for a picture, opens your Media Library. For your site logo it sets the Dark logo; for any other picture it adds a line to Other image pairs.

The page shows the result at once, and the panel says which list it went into, with Undo to take that one line off again. The lines are the same ones you see and can edit on Images and Elements. Press Escape to close the panel, Escape again to stop picking, and Stop fixing dark mode in the bar or the toolbar to leave.

It works with the keyboard too: while picking, the part that has the focus is outlined, and Enter picks it instead of following a link. Only parts that can take the focus (links, buttons, form fields) are reached that way. For a badge or a box, pick a link inside it and use Pick the part around it.

If you have Images and Elements open in another tab while you fix a page, reload that tab before you save it. Its form still holds the lists as they were when you opened it, and saving it would put them back that way.

What it does not do:

It names a part by its id, or else by its tag and up to two of its classes, or else by a short path of tags. It passes over ids and classes that look generated (a run of digits, a hash, a page builder's layout classes), since those change and the line would stop matching. A part with nothing stable about it gets a path, which the panel shows before you save.
Under the Basic method a part cannot be kept or inverted (the lists on Images and Elements are not applied there either), so the panel offers neither and says why. Under Invert everything is inverted already, so it does not offer Invert it. A dark version of a picture works under all three methods.
It names parts well enough that a line usually keeps working, not always: a theme or page builder update that renames a part means fixing it again.
It is for administrators only. Visitors never load the picker, its stylesheet or the Media Library; the dark mode script every visitor already gets has a few more lines, so a change shows without a reload. The fix-mode page is sent with headers that keep page caches from storing it.

Fine tuning#

Brightness, contrast, warmth and greyscale. Brightness and Contrast at 100%, with Warmth and Greyscale at 0%, change nothing, and that is where a new site starts: the palette you pick is exactly what visitors get, and True black is really black. The engine applies these four to every colour it draws, the palette included, so lower contrast or add warmth to soften the page if it glares.

A site set up before version 1.2.14 keeps the Contrast 90 and Warmth 10 it has always been drawn with, so nothing changes on it. The Colours preview now shows what those two do to the palette.