Light and dark mode for WordPress block themes https://www.lrob.fr/
  • PHP 72.1%
  • JavaScript 20.5%
  • CSS 5%
  • Shell 2.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Robin 511a115086 WordPress's black and white never change; no rule in the theme's own mode; mode event on system change (0.3.6)
- The default palette's black and white keep their variables in the
  other mode (other plugins use them as a sure black and white); they
  only get a text value where the content uses them as text. A value
  typed by hand is kept.
- The .has-<slug>-color rules are written under the other-mode
  selectors only: the theme's own mode gets nothing but its
  color-scheme. A test checks every rule for every default mode.
- The head script dispatches lrob-dark-mode:change when the system
  switches mode while the site follows it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PXWEBqh4Co91S6NWynLbPA
2026-11-21 21:46:30 +01:00
assets WordPress's black and white never change; no rule in the theme's own mode; mode event on system change (0.3.6) 2026-11-21 21:46:30 +01:00
blocks/toggle Send only the settings with REST requests; one-click admin mode; ink fix for other plugins (0.3.2) 2026-11-21 19:51:10 +01:00
languages Send only the settings with REST requests; one-click admin mode; ink fix for other plugins (0.3.2) 2026-11-21 19:51:10 +01:00
src WordPress's black and white never change; no rule in the theme's own mode; mode event on system change (0.3.6) 2026-11-21 21:46:30 +01:00
tests WordPress's black and white never change; no rule in the theme's own mode; mode event on system change (0.3.6) 2026-11-21 21:46:30 +01:00
tools Send only the settings with REST requests; one-click admin mode; ink fix for other plugins (0.3.2) 2026-11-21 19:51:10 +01:00
.gitignore Light and dark mode for block themes (0.1.0) 2026-11-20 21:15:52 +01:00
CHANGELOG.md WordPress's black and white never change; no rule in the theme's own mode; mode event on system change (0.3.6) 2026-11-21 21:46:30 +01:00
CLAUDE.md WordPress's black and white never change; no rule in the theme's own mode; mode event on system change (0.3.6) 2026-11-21 21:46:30 +01:00
LICENSE Light and dark mode for block themes (0.1.0) 2026-11-20 21:15:52 +01:00
lrob-dark-mode.php WordPress's black and white never change; no rule in the theme's own mode; mode event on system change (0.3.6) 2026-11-21 21:46:30 +01:00
publish.sh Switch the literal colors of the global styles with the mode (0.1.1) 2026-11-20 21:32:02 +01:00
README.md WordPress's black and white never change; no rule in the theme's own mode; mode event on system change (0.3.6) 2026-11-21 21:46:30 +01:00
release.sh Light and dark mode for block themes (0.1.0) 2026-11-20 21:15:52 +01:00
uninstall.php Dark administration built from WordPress's own styles, simpler color table (0.3.1) 2026-11-21 18:57:52 +01:00

LRob Dark Mode

Your block theme, in light and in dark, without redesigning a single page. Activate the plugin and your WordPress site follows each visitor's light or dark preference, with a toggle they can use and every color under your control.

Why

  • Comfort. A dark page in the evening, a light one in full daylight: your visitors read longer, and with less effort.
  • Accessibility. Some people need a dark background, others a light one. Both get a site that works for them, with text that keeps the contrast the accessibility standard asks for (WCAG AA).
  • Respect for their choice. Their system is set to dark? Your site is dark, from the very first page, with no flash of the wrong colors.
  • Light. A few kilobytes, no external library, font or script, no cookie. Your design, your pages and your blocks stay exactly as they are.
  • Your administration too. Each user of the site can switch the WordPress administration to dark, or let it follow their system.

Example

Your theme is dark: background #111111, text #eeeeee, a yellow accent #ffd400. With LRob Dark Mode:

  • a visitor whose system is set to light mode sees a background #eeeeee, text #111111, and the accent still bright on buttons, and deepened to amber where it is text, readable on the light background (you can adjust each color);
  • a toggle in the header lets them pick automatic, dark or light; the choice is remembered in their browser;
  • the page never flashes in the wrong colors on load: the mode is applied before the first paint.

How it works

WordPress publishes every color of the theme palette as a CSS variable (--wp--preset--color--<slug>), and blocks use those variables. The plugin gives these variables their other-mode values when the visitor's mode is not the theme's own.

Colors written by hand in the global styles (see below) are handled the same way: each one gets a variable of its own, with the original color as its fallback.

No content is rewritten, and turning the plugin off gives back the theme exactly as it was.

Installation

  1. Download lrob-dark-mode-<version>.zip from the releases of the repository.
  2. In WordPress: Plugins → Add New → Upload Plugin, choose the zip, activate.
  3. Go to Appearance → Light & dark mode.

Updates then appear in Dashboard → Updates like any other plugin. If the repository is private, add a read token to wp-config.php:

define( 'LROB_DARK_MODE_UPDATE_TOKEN', 'your-read-only-token' );

Settings

Appearance → Light & dark mode:

  • The theme is dark or light: the theme's own mode, read from the real background and text of your pages until you save it.
  • Visitors see: the mode of their system (default), or always light, or always dark until they choose.
  • Administration, by default: the mode of the WordPress administration for the users who have not chosen theirs (see Dark administration).
  • Conversion: how the colors are turned into the other mode (see below).
  • Two tabs, one per mode. The other mode: every color with its value there. The theme's own mode: the same colors, to check and correct the theme itself (see Fix the theme itself).
  • Each color shows its source (its swatch, name and code in the theme's mode) and its destination (its swatch and code in the other mode), each swatch outlined so that white on white shows; its value as text, only when the color really is text on your site, and the value then differs (when this color is text, it takes this value to stay readable), and its contrast (see How a contrast is measured). The colors your site does not use come last, folded under Not used on this site. Each value is proposed automatically. Click the destination swatch to change it: a small window opens right there, with WordPress's color picker, the code, Reset to the proposal, its value as text, and under Advanced the role of the color (guessed for you). Enter keeps the color, Escape gives back the one before. Tick Lock for a color that must stay the same in both modes. The ⓘ button lists where the color is used, ready to copy.
  • As text, your own choice. The value a color takes as text is computed to stay readable, in the same hue. When you would rather another color of your palette (a blue for your links instead of a darkened yellow), type it in As text in the color's window: its contrast shows next to it, in red when it falls short, and nothing stops you. Buttons keep the color's background value. Reset to the proposal goes back to the computed value.
  • Colors of the global styles: see below.
  • Preview: a real page of your site next to the settings (see below).
  • Site scan: Scan the site (see below).

Every change shows at once, in the table and in the preview. Nothing reaches your visitors until you save: the bar at the bottom says when changes are not saved yet, with Save Changes and Cancel the changes.

How a contrast is measured

A contrast is always measured between a text and the background it sits on, as your site uses them: the theme's styles (the button text on the button, links on the page...) and your content, read by the scan. Each color shows its worst pair, named with its two colors and where it is: button › text on button › background, Text in the content on Accent 1, Accent 2 on Page background. When a color is text on several backgrounds, Other backgrounds opens the others.

Conversion: presets and sliders

One click on a preset recalculates every proposal; values you typed stay as you typed them. Each preset shows a miniature of your page in its colors.

Preset What it gives
Tinted The page keeps a hint of your theme's hue: a navy dark theme gets a pale blue light mode.
Soft A page that is not quite white or black, gentler colors.
High contrast Text at 7:1 (WCAG AAA), a pure page, slightly richer colors.
Pure white / Deep black A pure white (or pure black) page, neutral surfaces.

Or set it yourself:

  • Method: lightness inverted (simple and predictable), perceptual (a color's contrast with black becomes the same contrast with white, hue and richness kept; accents keep their brightness, so a yellow button stays yellow), or contrast kept (each color keeps the contrast it had with your page, so secondary text stays secondary).
  • Text contrast: from 4.5:1 (WCAG AA) to 7:1 (AAA). Large headings need two thirds of it.
  • Saturation, background tint (how much of your theme's hue the page and surfaces keep: 0 is pure white or black) and softness (how far the page stays from pure white or black).

The role of each color

Role What it means for the conversion
Page background What everything is read on. The background tint applies.
Surface The background of blocks and sections. Never treated as text.
Text Text only: its own value is made readable, everywhere, even in a stylesheet that is not your theme's.
Accent A background and text: it keeps its value as a background (a yellow button stays yellow) and gets a readable value of its own where it is text.
Border Borders and decoration. Never treated as text.

The role is guessed from where the color is used: the global styles and your content. Under each color, the settings page says where: button:hover › text, core/search › background, text in the content. Change the role when the guess is wrong.

Live preview

Next to the settings, a real page of your site (the home page, or one you pick) is shown in the mode of the open tab, with the settings as they are on screen, before you save. Move a slider, pick a preset, change a role or a color: the page and the table follow while you move, computed in your browser in about a millisecond. On a wide screen the preview stays in view while you scroll the settings.

Every text on that page is measured, against the background it really sits on. The texts below the contrast they need are listed; a click shows one on the page.

Fix the theme itself

The tab of your theme's own mode uses the same tools on the theme as it is: its contrast, color by color, and a readable value suggested for each text that falls short (Use the suggestions, or one click on a suggestion). Type a corrected value where you prefer your own. The preview shows the corrected theme.

  • Apply to the theme writes the corrected colors into the styles of the Site Editor (the same place as Appearance → Editor → Styles), after a summary you confirm. WordPress keeps a revision: you can go back from Styles → Revisions. It does not depend on this plugin: the correction stays if you turn it off.
  • Export for the theme downloads a theme.json fragment with the corrected palette and styles, to copy into a block theme and make the correction part of the theme.

Export and import

Export the palette downloads a JSON file of every color and of the conversion settings, made to be read and edited by a person or by a tool (an AI assistant can do the mapping for you):

{
  "format": "lrob-dark-mode-palette",
  "version": 1,
  "theme": { "name": "Example", "mode": "dark" },
  "settings": {
    "base": "dark",
    "default": "auto",
    "conversion": { "method": "hsl", "contrast": 4.5, "saturation": 100, "tint": 100, "softness": 0 }
  },
  "colors": [
    {
      "slug": "accent-2",
      "name": "Accent 2",
      "value": "#ffb700",
      "role": "",
      "guess": "accent",
      "uses": ["button › background", "content › text"],
      "other": { "value": "", "keep": false, "text_value": "", "proposal": "#ffb700", "result": "#ffb700", "text": "#af5000" },
      "fix": ""
    }
  ],
  "literals": [
    { "hex": "#c3c3c3", "value": "#c3c3c3", "role": "", "guess": "text", "uses": ["body › text"], "other": { "value": "", "keep": false, "text_value": "", "proposal": "#3c3c3c", "result": "#3c3c3c", "text": "" }, "fix": "" }
  ]
}

What an import reads:

  • settings.base ("", "light", "dark"), settings.default ("auto", "light", "dark"), settings.conversion (method: "hsl", "oklch" or "contrast"; contrast: 4.5 to 7; saturation: 50 to 150; tint and softness: 0 to 100);
  • for each color (by slug) or literal (by hex): role ("" = automatic, or page, surface, text, accent, border), other.value (the value in the other mode, "" = automatic), other.keep (true: the color does not change), other.text_value (its value as text on the page in the other mode, "" = computed), fix (a corrected value for the theme's own mode, "" = none). Colors are hex, rgb() or hsl() values.

Everything else (name, value, uses, proposal, result, text) is there to read, and ignored. A color the file does not mention keeps its settings.

The import is strict: a value that is not exactly one of the above, or a color the theme does not have, rejects the whole file and lists every problem. Nothing is taken until you have seen what changes and confirmed it; then save to keep it.

Site scan

Scan the site reads your posts, pages, patterns, templates, navigation and theme files. It runs again on its own when the settings page opens and the last scan is out of date: another theme, a theme file changed, a content saved since. The date of the last scan is shown. Two lists, each with its count:

  • Hard-to-read text: each text / background pair below the contrast it needs, with its two colors named (a fixed color says so), its contrast, the mode (your theme's or the other) and where it is, with a link to edit it (the Site Editor's styles, the page, the template). The same colors on the same kind of element make one line, with their number and the places, folded. Problems of the theme itself come first. Text colors written as fixed values are the usual cause in the other mode: they do not change while the background does.
  • Fixed colors, which don't change mode: each color written as a fixed value, with where it is. When a palette color has the same value, Use "" replaces it in your content, after a summary you confirm, the way the block editor writes a palette color: the color then follows the mode. WordPress keeps a revision of each page changed.

Not fixed, and not listed: fully transparent colors, color-mix(), var() values, palette colors, and the colors of the global styles (the plugin switches those). The files of a parent theme come apart, folded: you cannot change them from your site, and only the patterns your site really uses are listed.

Readable text in both modes

Inverting a color is not enough: a yellow accent, a sky-blue link or a pale title can read well on a dark page and poorly on a light one. So every color used as text gets a value that reaches at least 4.5:1 on its background in the other mode (3:1 for level 1 and 2 headings), the WCAG AA level.

A color keeps two values in the other mode:

  • as a background (its palette variable): the proposal, or the value you set. A yellow button stays yellow;
  • as text, only when that value is not readable: the theme's own color if it reads (black text on the yellow button), else the color darkened or lightened just enough. This is done in OKLCH, a perceptual color space, keeping the hue and the richness of the color; a yellow that must darken turns amber or burnt orange instead of olive.

The text value is used wherever the color is set as text: text colors chosen on blocks (.has-<slug>-color), text, links and headings in the global styles, the link and heading colors set on a block, and palette colors written as a CSS variable, var(--wp--preset--color--<slug>, #hex), in a block's settings or in the HTML of the content (a highlighted word, a <span>). Backgrounds and borders written the same way keep the color's background value.

Two kinds of blocks are handled on their own:

  • A block on a fixed background (an opaque background written as a value, not chosen from the palette; a cover's own overlay color at full opacity) does not change with the mode, so its content keeps your theme's colors in the other mode too: the text that was made to read on it still does. Limit: a translucent fixed background lets the page show through, and the page does change; such a block is treated like the page, and its text is not guaranteed to reach 4.5:1 on the mix. A background from the palette avoids this.
  • A cover block without a text color of its own, on an overlay from the palette: WordPress writes its text in white (or black), whatever the overlay becomes. In the other mode, with an overlay at half or more, its text takes the color of your site (text or page) that reads best on the overlay's new value. With a fainter overlay, over an image the image decides and the text stays as you made it; over no image, the text follows what is below it.

Out of reach: colors written as fixed values (the scan lists them), colors set in a theme's or a plugin's own stylesheet, and HTML written outside blocks.

Text is checked against the background it really sits on, each with its own value: the page, a button, a section style, a block with a background color. Black text on a yellow button and white text on a dark section can come from the same palette color. When the page background is a gradient, text on the page is made readable on each of its colors, from the top of the page to the bottom; the preview measures each text on the least favorable point of its gradient.

The plugin knows a color is used as text from:

  • the global styles: body text, links, headings, button text on the button background;
  • your content: text, link and icon colors set on blocks or written in their HTML, and the background they sit on (the element's own, the block's, an enclosing group, or the page). This index is built in the background when the plugin starts, kept up to date when you save a post, and rebuilt by Scan the site;
  • the colors themselves: a palette color readable on the page in your theme's mode can be text anywhere, so it stays readable in the other mode too.

A value you typed, or a color marked Does not change, is never altered: its contrast is shown, flagged when short, and the choice stays yours.

Colors written in the global styles

Many themes, child themes above all, set some colors directly in their styles instead of using the palette: the text of the page, links, headings, buttons, the background of a block. Left alone, those colors would stay the same in both modes, and a light text could end up on a light background.

The table Colors of the global styles lists each of them once, with where it is used (body › text, link:hover › text, button › background, core/quote › border...), and gives it a value for the other mode, proposed automatically like a palette color. Change it, or tick Does not change.

It covers the styles of your theme (theme.json), the ones set in the Site Editor, and the WordPress defaults (such as the button colors). The Site Editor keeps showing and saving your colors exactly as you wrote them.

The colors of WordPress's own palette (vivid red, luminous vivid amber...) are handled like your theme's when your site uses them, in its content or in its styles: they appear in the palette table, with a proposal, a contrast and a value in the other mode. Except black and white: they mean exactly that, and other plugins use them as a sure black and a sure white, so they never change with the mode. Where your content uses them as text, they still get a readable value as text (white text on a page that turns light, for instance). A value you typed for them yourself is kept.

Dark administration

Each user chooses the mode of the WordPress administration for themselves with the button of the toolbar: a click goes to the next mode, the mode of their system, dark, light, in turn, at once and kept for them. Until a user chooses, the site's default applies: the mode of their system, unless the administrator sets another one on the settings page. It is independent of the mode of your public site.

Two styles of dark, for each user in their profile (Dark mode style): Dark, a soft graphite, and Deep black, a pure black page for OLED screens.

The dashboard and its boxes (Activity, At a Glance, Quick Draft, Site Health, Events and News), lists, comments, media, plugins, settings, profile, menus and the block editor's interface (toolbars, sidebars, popovers) turn dark, with no flash on load and text at 4.5:1 at least. The colors come from WordPress's own stylesheets, each one given its dark equivalent, so that states keep their meaning: a warning stays yellow, an error red, a primary button blue. The content you edit in the block editor keeps the colors of your site.

On the screens of other plugins, a text never ends up light on a box that stayed light, or dark on the dark page: each text below 4.5:1 on the background it really sits on gets the ink that reads there, and the plugin's boxes keep their own design. A box in a gradient is read on its least favorable color, and colors in any form a browser computes are understood (color-mix(), oklch()...). Text on an image is left as it is. It takes a few milliseconds when the page opens, and again only for what the page writes or restyles later (a preview filled in by the plugin's script, a box opened) and when you switch the mode.

For plugin authors

To fit the dark administration, style your screens under the class it sets on <html>, or use its colors as variables with your own as fallback:

.my-card {
	background: var(--lrob-adm-surface, #fff);
	color: var(--lrob-adm-text, #1d2327);
	border-color: var(--lrob-adm-line, #dcdcde);
}
html.lrob-adm-dark .my-chart { filter: invert(1) hue-rotate(180deg); }
Exposed What it is
html.lrob-adm-dark The administration is dark right now.
html.lrob-adm-black With the Deep black style.
html[data-lrob-adm] The user's choice: light, dark or auto.
lrob-adm-change Event on document when the mode changes.
--lrob-adm-page, --lrob-adm-surface, --lrob-adm-raised, --lrob-adm-hover The page, a panel, a field or raised area, a hovered row.
--lrob-adm-line, --lrob-adm-edge A light border, a stronger one.
--lrob-adm-text, --lrob-adm-muted, --lrob-adm-faint Text, secondary text, placeholder.
--lrob-adm-link, --lrob-adm-link-hover Links.
data-lrob-adm-ink Set by the plugin on a text it had to re-ink (dark or light).

The variables are only defined in dark mode, hence the fallback. Set a text color wherever you set a background, and the WordPress classes (.card, .postbox, .widefat, .notice, .button, .form-table) are dark already.

The toggle

  • Block: Light / dark toggle (category Theme), to place in a header or footer template part. Its size follows the font size setting. In its panel, Appearance: the style (icon in a circle, icon only, icon and name of the mode) and the width (its own, or 25 to 100 % of its container); alignment is WordPress's own.
  • Shortcode: [lrob_dark_mode_toggle], for places that take shortcodes, with the same options: [lrob_dark_mode_toggle appearance="label" width="100" align="center"] (appearance: circle, icon or label; width: 25, 50, 75 or 100; align: left, center or right).

The button takes the color of the text around it. It cycles through automatic → dark → light (or dark ↔ light when the site has a fixed default mode). It is hidden when JavaScript is off, where it could not work; the system's mode still applies.

For developers

  • The visitor's explicit choice is the attribute data-lrob-dm="light|dark" on <html>; without it, the site default applies. Style your own components with the palette variables and they follow the mode with nothing else to do.
  • The event lrob-dark-mode:change is dispatched on document every time the mode of the page changes without a reload: a click on the toggle, a choice made in another tab, and the visitor's system switching light or dark while the site follows it. detail.mode is the visitor's choice (auto, light, dark) and detail.scheme the mode now shown (light or dark). A component that reads colors once (at load) should read them again on this event: the palette variables have already changed when it fires.
  • WordPress's own black and white (--wp--preset--color--black, --wp--preset--color--white) never change with the mode: you can rely on them as a true black and a true white.
  • The choice is kept in localStorage under lrob-dark-mode: no cookie is set.
  • A literal color of the global styles is output as var(--lrob-dm--<hex>, <color>).
  • The text value of a palette color, when it has one, is --lrob-dm-text--<slug> (defined in the other mode only); use var(--lrob-dm-text--<slug>, var(--wp--preset--color--<slug>)) for text in your own components.

Performance

  • The CSS of the other mode is a few kilobytes (about 6 KB for a full theme, under 1 KB compressed), minified, and inlined in the <head>: no extra request, and no flash of the wrong colors. A separate file would cost the first visit one more request that blocks the page, for less than a kilobyte.
  • It is computed when you save the settings, after a scan, or in the background (wp-cron) when the theme changes; a visit only reads it. Checking that it is up to date costs a few hundredths of a millisecond.
  • The live preview and the contrast measures run in your browser, on the settings page only: the same computation as the one your visitors get, in JavaScript, with no request.
  • What a visitor's page gets: a head script of 190 bytes and the CSS of the other mode, both in the page; the toggle's styles (2.6 KB) written in the page too, and its script (2.7 KB) deferred. No request blocks the first paint, and the first paint is the same with the plugin as without it, measured with a CPU slowed down 4 and 6 times. On the server, a page that is not cached costs about 3 ms more: mostly writing the colors of the global styles as variables, which is what lets them change with the mode.
  • The dark administration is only loaded when it can be dark: never in light mode, and in the mode of the system only when the system is dark. Its stylesheets (12 KB compressed for the screens, 10 KB more on the block editor's screens) cost a page about 4 ms to read and apply, 50 ms with a CPU slowed down 6 times.
  • The settings page sends its requests to its own address and renews an expired session token on its own; when a request still fails, it says why, with a Retry button.

For maintainers

The dark stylesheets of the administration are built from WordPress's own: php tools/admin-dark.php /path/to/wordpress screens > assets/css/admin-dark-wp.css and php tools/admin-dark.php /path/to/wordpress editor > assets/css/admin-dark-editor.css. Run it again when a new version of WordPress changes the look of its administration.

Security

  • Every color value that reaches the page is parsed and rewritten as a plain hex color; nothing typed in the settings can inject CSS.
  • The scan only reads: posts and theme files are read as text, never executed or included, and everything shown is escaped. Block attributes are only decoded as JSON.
  • An imported palette file is only decoded as JSON; every value is checked against what the format allows, and the file is rejected as a whole at the first doubt.
  • Settings, scan, import, Apply to the theme and Use "" require the edit_theme_options capability, the one the Site Editor itself requires; Use "" also requires the right to edit each page it changes, and only changes blocks where the color is written the way the block editor writes it.
  • The mode of the administration is a setting of each user, which they change for themselves.
  • The update token, when used, is only sent to the repository's own server.

Requirements

  • WordPress 6.7 or later, with a block theme (a theme with a theme.json palette).
  • PHP 8.4 or later.
  • No external library, no external font or script.

License

GPL-2.0-or-later. © LRob.