Add a dark theme, chosen in the settings or following the system

[zaerl]

Why

#560, and the last row of #559's dialog. The window painted light only, and said so: its colour-scheme declaration was held to light by a test, since the older component library ships light styles and a promise of dark that only reached the native form controls gave charcoal inputs on white cards. A contributor whose machine is in dark mode got a white window all evening, with no way to say otherwise. This adds a dark theme, chosen in the settings or following the system.

What changes

Theme, on the General tab, under Appearance: Light, Dark or System, which is the default and follows the operating system. A change is on screen as it is made; nothing running is touched. The prototype's fourth answer, a custom pair of colours, is not offered.

One source of truth. Main gives the choice to Electron's nativeTheme, read from the store before the window is made and set again as the setting changes. Chromium answers the page's prefers-color-scheme from it and paints the window's chrome and the native form controls to match, so the window only reads that answer: a wrapper around the design system's provider seeds the dark ramp from the prototype's dark background when the scheme is dark, and passes no colour when it is light, so the light theme is pixel for pixel what it was and no picture in the guide moves. The provider builds every token from the seed, for its own components, for the older library's through the variables it maps for them, and for the app's own styles; the diff and log panes follow through their tokens.

What the provider does not reach. The terminal takes its colours as values and reads them again when the scheme changes. The older library's dialogs and popovers are painted white in its own stylesheet, with no token behind the colour, and are painted here with tokens; the popover's ring and shadow are restated in the dark scheme only.

No white before the page paints. A dark window is made in the dark colour and kept in it as the theme changes, and the page paints its body the same colour under the dark scheme until the provider has mounted, which it marks on the document. color-scheme.test.cjs now holds the declaration to light dark and that colour to the theme module.

The pictures and the journeys. Playwright holds a page to the light scheme whatever the machine says, so the guide's pictures are pinned to light through the app's own setting (SHOTS_THEME=dark for a dark one), and every journey stays light; the theme journey alone lets the page follow the app.

Not in this pull request:

• The patch and Trac windows, which are made without a theme and paint their own bar white. Follow-up.
• A custom theme.
• Mail rendering is unchanged here and tracked separately.

How to test this

Platforms: any. The journeys drive this on macOS and Windows. From the repository root, after npm ci and npm run build:once:

npx playwright test --project=journeys settings.spec i18n.spec terminal.spec logs.spec

• settings.spec.js, the theme journey: stored dark, the window starts dark, Electron is told, the body and the terminal are painted with the dark tokens; Light chosen is kept, Electron is told, the page, the body, the terminal and the window's own colour are light at once with no relaunch; System is kept and the window is the colour of whichever theme Electron then says; started again with dark kept, the window is made dark and the control says so.
• i18n.spec.js: the control in the pseudo-locale.
• terminal.spec.js, logs.spec.js: the terminal's and the panes' colours are the tokens, as before.

I broke six claims one at a time and each was caught: the stored theme not applied at startup, the setting not telling Electron, the window not made dark, the terminal not re-reading its colours, the page not seeded dark, the window not painted on a setting change (the last by ipc-wiring.test.cjs; the journey is kept green by Electron's own updated for that case). tests/unit/theme.test.cjs, settings.test.cjs, settings-view.test.cjs and color-scheme.test.cjs hold the model, the control's entries and the page's declaration.

Worth a look by hand (any platform, the current head): Settings → General → Theme. Press Dark: the whole window, the dialog you are in and the footer's Give feedback popover are dark at once; the site menu, the create-site dialog and the review dialog's diff are dark when opened. Open the Terminal tray before and after: it follows. Press System and change your machine's appearance: the window follows. Quit with Dark kept and open the app: it opens dark, with no white flash.

What must not have happened: the light theme looking any different from before (the guide's pictures are the reference); a white window or page in the moment before a dark page paints; the terminal keeping the old colours after a switch; a server or build stopped or started by the change.

What I could not test: Windows, where the journeys run in CI; the system's theme changing under System by hand, which the unit test drives through Electron's updated with a stubbed answer, and which I could not stage on the Mac without changing its appearance under the running suite. The pictures of the dark theme in this description were taken with SHOTS_THEME=dark and are not in the diff: the guide shows the light theme.

Risks and limitations

• Review: 2 passes, 6 findings fixed here, 1 follow-up left (the patch and Trac windows), every style note applied. Details below.
• The patch and Trac windows stay white under Dark, as they were. Follow-up.
• The dark theme is the design system's ramp from one seed, not a hand-made palette: a surface or a stroke that reads wrong in dark is the ramp's to fix, and the one token the app sets by hand is the pre-mount body colour, held to the seed by a test.
• The older library's buttons keep a handful of literal colours for a disabled or a destructive state, readable in dark but not the ramp's.

Related

Closes #560. Part of #559, which is part of #542. Follows #641.

---

Design decisions and alternatives considered

• nativeTheme as the one place the choice is made. The prototype resolves 'system' in the page with matchMedia. Here main resolves nothing: it gives Electron the setting, and the page reads prefers-color-scheme, which Electron answers from it. One chain, setting → Electron → page → tokens, and the window's chrome and the native controls come with it.
• No seed in the light scheme. Generating the light ramp from a seed moves every colour by a hair; the tokens stylesheet already holds the light values, and the guide's pictures show them.
• The window's own colour set from the setting, not left to updated. Electron promises the event for a change to light or dark, not to system; the listener stays for the system's theme changing under 'system'.
• A pre-mount body rule in index.html, scoped to before the provider mounts. The page's first paint is before its script runs; the rule stops at the attribute the provider sets, so the ramp's surface is the body from then on. The colour is the seed, and a test holds the two together.
• Three themes, not four. A custom pair of colours is a feature the prototype has and nobody has asked for.

Review outcome (required — see AGENTS.md)

Pass 1: 3 [fix here] · 1 [follow-up] · 5 style notes. Pass 2 (on the fix-up): 3 [fix here] · 0 [follow-up] · 1 style note. All 6 fixed here, every style note applied, 1 follow-up left.

• Review: completed — a separate agent context, read-only; head 8a7457b / base 3866e1a; the store rule checked against the startup read and the handler, the provider's effect ordering against React's commit phases, the pre-mount rule's specificity, the deep-link path that can open the window before the ready path, the old library's rules the shell overrides, translation extraction; ESLint and the unit files run; 3 [fix here], 1 [follow-up].
  • Fixed: the window's colour was set once and went stale on a theme change, an OS change and a deep link's early window; the journey read the light body before the app had repainted; the popover's ring and shadow were restated in the light theme too, and a menu-group rule matched nothing.
  • Follow-up left: the patch and Trac windows are not themed.
  • Style notes, applied: a stale comment on the store's first read; translator context for the theme's words; SHOTS_THEME checked; the tests naming the colours by their constants; a unit test that restated constants.
• Review: completed — a second separate agent context, read-only; head 64cad1a / base 3866e1a; the updated listener against Electron 43's documentation, the stub's assumptions, the light theme against the library's and the tokens' values; ESLint and the unit files run; 3 [fix here].
  • Fixed: nothing showed Electron emits updated for a change to 'system', so the window is painted from the setting itself and the journey reads the window's colour; a test's name claimed a deep link's window it did not exercise; SHOTS_THEME=system passed the check that exists to keep the system's theme out of the pictures.
  • Style note, applied: the dark popover's soft layer is a glow, and the comment says so.
• Since review: 64cad1a → HEAD is those three and the note, not reviewed again. On the head: npm run lint, npm test, npm run test:electron (2029), all 124 journeys, the packaged smoke and the docs build pass.

Implementation notes

• src/theme.cjs: THEMES, themeColorSeeds, windowBackground, the two seeds. src/settings.cjs: theme. src/main.js: applyStoredTheme, paintWindowForTheme, the updated listener, backgroundColor on the window, settings:set.
• src/renderer/components/app-theme.jsx: AppTheme, useDarkScheme. src/renderer/index.jsx: mounted under it. src/renderer/hooks/use-site-terminal.jsx: the re-read. src/renderer/terminal-theme.cjs: the header. src/renderer/shell.css: the old library's dialogs and popovers. src/renderer/index.html: color-scheme and the pre-mount rule.
• src/renderer/settings-view.cjs: themeItems. src/renderer/components/settings-dialog.jsx: ThemeControl.
• scripts/screenshots/fixtures.cjs: SHOTS_THEME. scripts/screenshots/capture.cjs, tests/e2e/helpers/app.cjs: colorScheme.
• Tests: tests/unit/theme.test.cjs, color-scheme.test.cjs, settings.test.cjs, settings-view.test.cjs, ipc-wiring.test.cjs (the electron stub's nativeTheme); tests/e2e/journeys/settings.spec.js.

Screenshots or recording

Not attached: I have no way to upload images from the command line. SHOTS_THEME=dark npm run shots takes the guide's pictures in the dark theme into docs/public/screenshots/ for a look (and leaves them changed; restore them after).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: WordPress/contributor-toolkit/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: e80f978e-8790-4a51-bd28-792ceadf3b4a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}