Dark mode
A dark palette, a default mode, a visitor toggle, and images that swap in dark mode.
A site has a light palette and an optional dark one. You pick which one visitors see first, and they can switch with a Theme toggle block.
Colors
Open Settings → Colors, or Site Colors in the editor's Design panel. Click Add Dark Palette to add the dark side; light and dark then sit side by side. Each palette has seven tokens:
| Token | Used for |
|---|---|
| Background | Page background |
| Foreground | Body text |
| Primary | Buttons, links, accents |
| Primary foreground | Text on primary (button labels) |
| Muted | Secondary text and quiet backgrounds |
| Surface | Cards and panels. Defaults to a mix of Muted |
| Border | Dividers and outlines. Defaults to a mix of Foreground |
Each text pair (Text on Background, Text on Muted, Primary Foreground on Primary) shows a contrast badge: AA passes for body text (4.5:1), AA Large passes for large text only (3:1: 24px, or 19px bold), and anything lower is too low to read comfortably. Check both palettes; a pair that passes in light can fail in dark.
Suggest Dark Palette builds a toned-down dark palette from your light colors. Review it, then save. Remove drops the dark palette.
Color changes go live the next time you publish.
Default mode
Default mode is what first-time visitors see, before they use a theme toggle.
| Default mode | First visit shows |
|---|---|
| Light (default) | The light palette |
| Dark | The dark palette |
| Match System | Whatever the visitor's device is set to |
A site without a dark palette always shows light. Existing sites stay light until you change this.
Theme toggle
Add the Theme toggle block, usually to the site header. Visitors pick Light, Dark, or System. Icon is one button that cycles through the three; Segmented shows all three. The choice is stored in a cookie (pw_site_mode) on your domain, and the server reads it before sending the page, so there is no flash of the wrong colors on reload.
The toggle is hidden on the live site until the theme has a dark palette. In the editor it shows the hint "Add a dark palette in Colors first".
The colors cross-fade for 200 ms when someone switches, and change instantly for visitors who ask for reduced motion.
Use theme tokens in blocks
Only colors that come from the palette change with the mode. A block with a fixed color like #ffffff stays white in dark mode.
On any color field, choose Use Theme Token… and pick a token instead of a fixed color. The block then stores var(--site-background), var(--site-primary), and so on, and follows the mode. New starters use tokens already.
| Token | CSS variable |
|---|---|
| Background | var(--site-background) |
| Foreground | var(--site-foreground) |
| Primary | var(--site-primary) |
| Primary foreground | var(--site-primary-foreground) |
| Muted | var(--site-muted) |
| Surface | var(--site-surface) |
| Border | var(--site-border) |
Dark-mode images
Logos and screenshots often need a second version for dark backgrounds. On an Image block, set Dark Mode Image to another file from Storage. Visitors in dark mode see that one instead. Browsers only download the image for the mode in use.
Preview
The editor toolbar's canvas color mode switch shows the page in light or dark so you can check both palettes before you publish.
With MCP or the API
planeward-site-update takes the palette in theme: the light tokens, dark (all seven tokens, or null to remove it), and defaultMode (light, dark, or system). Image blocks take custom.darkSrc (a /media/{assetId} path). Theme toggle blocks take custom.toggleStyle (icon or segmented).
Planeward Docs