Theme tokens
The CSS custom properties a theme sets: base, state, surface and shape tokens, with their defaults.
A theme is a set of CSS custom properties on :root. The defaults, at the Light theme’s values, are in apps/desktop/static/styles/tokens/defaults.css. The app’s stylesheets, the UI kit and the bundled plugins all read these tokens, so setting them recolours the whole app.
How tokens resolve
- Names follow shadcn, plus a few Airpost additions, then surface, state and shape tokens. There are no per-component tokens.
- Most tokens derive from others. Setting
--foregroundalso moves--subtle-foreground,--muted-foreground,--accentand so on, unless you set those too. - Custom properties resolve on the element that declares them, so declare yours on
:root. defaults.cssloads before the theme’s tokens, so any theme rule on:rootwins.- System accent. While “use system accent” is on, the app sets
--system-accentand--system-accent-darkon:root. To follow it, write--primary: var(--system-accent, <your colour>).
Load order: defaults.css, core stylesheets, the kit, plugin styles, then the theme’s tokens.css.
Scheme
A theme declares "scheme": "light" or "dark" in its package.json, and "sidebarScheme" when its sidebar differs from the rest (as Darkside does). The app puts theme-scheme-light or theme-scheme-dark and theme-sidebar-scheme-light or -dark on body. Under a dark scheme, some image icons are inverted. Without a declaration the scheme is light.
Base tier
| Token | Meaning | Default |
|---|---|---|
--background | Window and content background | #ffffff |
--foreground | Body text | #231f20 |
--card / --card-foreground | Raised content, such as message cards | var(--background) / var(--foreground) |
--popover / --popover-foreground | Menus, popovers | var(--secondary) / var(--foreground) |
--primary / --primary-foreground | Accent, and text on it | var(--system-accent, #1f70ec) / #ffffff |
--secondary / --secondary-foreground | Secondary background | #f4f6f9 / var(--foreground) |
--muted | Off-white panels (composer action bar, attachments, calendar) | #fdfdfd |
--muted-foreground | De-emphasised text | --foreground at 60% |
--accent / --accent-foreground | Subtle hover background | --foreground at 5% / var(--foreground) |
--destructive / --destructive-foreground | Destructive actions | #d9534f / #ffffff |
--border | Dividers and borders | --secondary mixed 90% with black |
--input | Input and select borders | Derived from --background |
--ring | Focus ring | var(--primary) |
Airpost additions:
| Token | Meaning | Default |
|---|---|---|
--subtle-foreground | Secondary text (sidebar items, snippets) | --foreground at 85% |
--heading-foreground | Headings, toolbar text | #3a3f47 |
--link / --link-hover | Links | #1f70ec / #1a5fcc |
--control / --control-foreground | Text inputs, selects, default buttons | #ffffff / var(--foreground) |
--control-border | Button outline | var(--shadow-color) |
--shadow-color | Shadows and hairline borders | rgba(0, 0, 0, 0.15) |
State tier
| Token | Meaning | Default |
|---|---|---|
--hover | Hover background | var(--accent) |
--selected / --selected-foreground | Strong selection: focused row, active item | var(--system-accent-dark, …) (10% darker --primary) / var(--background) |
--unread | The thread list’s unread dot | #258fe1 |
--success / --warning / --danger / --info | Status colours | #5cb346 / #f0ad4e / var(--destructive) / #1c65d4 |
Surface tier
Each surface defaults to base or state tokens, so you only set what differs.
| Surface | Tokens |
|---|---|
| Toolbar | --toolbar-background, --toolbar-foreground, --toolbar-muted-foreground, --toolbar-border |
| Column toolbars | --sidebar-toolbar-background, --thread-list-toolbar-background, --message-list-toolbar-background (all transparent, so the toolbar shows through) |
| Sidebar toolbar buttons | --sidebar-toolbar-button, --sidebar-toolbar-foreground, --sidebar-toolbar-muted-foreground |
| Nav rail | --rail-background, --rail-foreground, --rail-border, --rail-hover, --rail-selected, --rail-selected-foreground, --rail-card-inset (a number: 1 insets the content card beside the rail, 0 joins it flush) |
| Sidebar | --sidebar-background (#f1f3f7), --sidebar-inset-background, --sidebar-foreground, --sidebar-muted-foreground, --sidebar-border, --sidebar-separator, --sidebar-hover, --sidebar-selected, --sidebar-selected-foreground, --sidebar-control, --sidebar-control-foreground, --sidebar-control-placeholder |
| Thread list | --thread-list-background, --thread-list-foreground, --thread-list-muted-foreground, --thread-list-border, --thread-list-hover, --thread-list-unread, --thread-list-unread-foreground, --thread-list-read-foreground, --thread-list-selected (and -foreground, -border), --thread-list-focused (and -foreground, -border), --thread-list-cursor, --thread-list-focused-icon-whiten (a number; set 0 for a pale focused row) |
| Reading pane | --message-list-background (var(--secondary)), --message-list-foreground, --message-list-muted-foreground, --message-list-border |
| Composer | --composer-background, --composer-foreground, --composer-muted-foreground, --composer-border |
| Menus and popovers | --menu-background, --menu-foreground, --menu-muted-foreground, --menu-border |
| Modals | --modal-background, --modal-foreground, --modal-muted-foreground, --modal-border, --modal-overlay |
The sidebar tokens also apply to the Preferences, contacts and calendar sidebars.
Shape tier
| Token | Meaning | Default |
|---|---|---|
--radius | Base radius; the steps scale from it | 3px |
--radius-sm / --radius-md / --radius-lg | 2px / var(--radius) / 5px | |
--font-sans | UI font | 'Albert Sans', 'Helvetica', sans-serif; system-ui on Windows |
--font-serif / --font-mono | Georgia stack / DejaVu Sans Mono stack | |
--font-heading | var(--font-sans) | |
--font-size | Base UI text size | 14px |
--density | Padding multiplier for kit components | 1 |
--row-height / --row-height-narrow | Thread list row height, wide and narrow | 36px / 85px |
Keep the row heights plain lengths; the thread list reads them as numbers.
Other values
Spacing, font sizes and the palette are not tokens. They are custom properties in apps/desktop/static/styles/variables.css (--spacing-standard, --font-size-small, …), which plugin CSS can read but themes normally leave alone.
LESS themes
Mailspring themes set LESS variables (styles/ui-variables.less) instead of tokens. Airpost still loads them: a theme with styles/ui-variables.less and no styles/tokens.css gets its tokens derived from its variables, for example @background-primary to --background, @text-color to --foreground, @accent-primary to --primary, @source-list-bg to --sidebar-background. This path goes away at plugin API 2.0, and some variables no longer reach the app’s styles. Write new themes as tokens.