Creating a theme
Build an Airpost theme in plain CSS by setting theme tokens, add preview colours, and test it in the app.
An Airpost theme is a package with a package.json and two CSS files: styles/tokens.css, which sets theme tokens on :root, and styles/theme-colors.css, which gives the colours for its preview tiles. To install a finished theme, see Themes.
Structure
my-theme/
├── package.json
├── styles/
│ ├── tokens.css # the theme's tokens on :root
│ ├── theme-colors.css # preview colours
│ └── *.css # optional extra rules, loaded after the app's
├── LICENSE.md
└── README.md
Steps
Copy a bundled theme
Start from one of the themes in apps/desktop/themes/: ui-light, ui-dark, ui-darkside, ui-taiga or ui-less-is-more. Copy ui-dark for a dark theme.
Edit package.json
{
"name": "my-theme",
"displayName": "My Theme",
"theme": "ui",
"scheme": "dark",
"version": "1.0.0",
"license": "GPL-3.0-only",
"engines": { "airpost": "*" }
}
theme must be "ui". scheme is light or dark; add "sidebarScheme" if your sidebar’s scheme differs from the rest.
Set tokens
In styles/tokens.css, set only the tokens you want to change. The rest derive from them.
:root {
--background: #111111;
--foreground: #e8e8e8;
--secondary: #151515;
--primary: var(--system-accent, #4d8ff4);
--border: rgba(255, 255, 255, 0.08);
--control: #1f1f1f;
--sidebar-background: #0b0b0b;
--shadow-color: rgba(0, 0, 0, 0.5);
}
Writing --primary as var(--system-accent, …) keeps the “use system accent” setting working.
Set preview colours
The tiles in Preferences > Appearance and the theme picker draw every theme at once, so they can’t read the active tokens. Give them colours in styles/theme-colors.css:
.theme-preview {
--theme-preview-sidebar: #0b0b0b;
--theme-preview-content: #151515;
--theme-preview-accent: var(--system-accent, #4d8ff4);
--theme-preview-text: #e8e8e8;
--theme-preview-background: #111111;
--theme-preview-active: #3a6fc4;
--theme-preview-toolbar: #0b0b0b;
--theme-preview-panel: #0b0b0b;
--theme-preview-swatch-border: rgba(232, 232, 232, 0.35);
}
sidebar, content, accent and text draw the Appearance tile; background, text, active, toolbar, panel and swatch-border draw the picker’s. The .theme-preview selector matches nothing in the app. Keep these in step with tokens.css.
Install and test
Use Install Theme… in the app menu (the Airpost menu on macOS, the Edit menu elsewhere) and pick your folder, or copy or symlink it into <profile>/packages/. Switch to it in Preferences > Appearance. Theme switching is live, so you can switch away and back after editing; Developer > Reload also picks up changes.
A complete theme: Harbor
This is a full light theme with a dark sidebar, the same shape as the bundled Darkside ("scheme": "light", "sidebarScheme": "dark"). Every token it sets is in Theme tokens; everything else derives from them through apps/desktop/static/styles/tokens/defaults.css.
package.json
{
"name": "ui-harbor",
"displayName": "Harbor",
"theme": "ui",
"scheme": "light",
"sidebarScheme": "dark",
"version": "1.0.0",
"description": "Light reading pane, navy sidebar.",
"license": "GPL-3.0-only",
"engines": { "airpost": "*" }
}
sidebarScheme makes the app put theme-sidebar-scheme-dark on body, so sidebar icons are inverted for the dark panel while the rest stays light.
styles/tokens.css
/* Harbor: light content, navy sidebar. Unset tokens follow defaults.css. */
:root {
/* Base */
--background: #ffffff;
--foreground: #1d2433;
--card: #ffffff;
--popover: #ffffff;
--secondary: #f3f5f8;
--muted: #fafbfc;
--primary: var(--system-accent, #2f6fdb);
--primary-foreground: #ffffff;
--destructive: #c8443c;
--border: #e1e5ec;
--input: #cfd5df;
/* Airpost additions */
--heading-foreground: #121826;
--link: var(--primary);
--link-hover: color-mix(in srgb, var(--primary), black 15%);
--control: #ffffff;
--control-border: #cfd5df;
--shadow-color: rgba(18, 24, 38, 0.12);
/* State */
--selected: var(--system-accent-dark, color-mix(in srgb, var(--primary), black 10%));
--selected-foreground: #ffffff;
--unread: var(--primary);
--success: #3c9a5f;
--warning: #d9902f;
/* Toolbar: the same navy as the sidebar, flat */
--toolbar-background: var(--sidebar-background);
--toolbar-foreground: #e6ebf5;
--toolbar-muted-foreground: #9aa6bd;
--toolbar-border: rgba(255, 255, 255, 0.06);
/* Nav rail and sidebar */
--rail-background: var(--sidebar-background);
--rail-card-inset: 0;
--sidebar-background: #18243a;
--sidebar-foreground: #dbe2ef;
--sidebar-muted-foreground: #8f9bb3;
--sidebar-border: rgba(255, 255, 255, 0.06);
--sidebar-hover: rgba(255, 255, 255, 0.05);
--sidebar-selected: rgba(255, 255, 255, 0.1);
--sidebar-selected-foreground: #ffffff;
--sidebar-control: rgba(255, 255, 255, 0.08);
--sidebar-control-foreground: #e6ebf5;
/* Thread list */
--thread-list-background: var(--background);
--thread-list-border: var(--border);
--thread-list-read-foreground: #5a6378;
--thread-list-focused: #e8f0fd;
--thread-list-focused-foreground: var(--foreground);
--thread-list-focused-icon-whiten: 0;
/* Reading pane */
--message-list-background: var(--secondary);
/* Shape */
--radius: 4px;
--radius-lg: 8px;
}
Notes on the choices:
--primaryand--selectedgo through--system-accentand--system-accent-dark, so “use system accent” in Preferences > Appearance still works.- The focused row is pale, so
--thread-list-focused-icon-whiten: 0keeps icons dark on it. --rail-card-inset: 0joins the nav rail and sidebar into one navy column.- Row heights (
--row-height,--row-height-narrow) are left alone. If you set them, keep them plainpxlengths, because the thread list reads them as numbers.
styles/theme-colors.css
The previews read this file directly (src/packages/theme-preview.ts); in the app the selector matches nothing.
.theme-preview {
--theme-preview-sidebar: #18243a;
--theme-preview-content: #f3f5f8;
--theme-preview-accent: var(--system-accent, #2f6fdb);
--theme-preview-text: #1d2433;
--theme-preview-background: #ffffff;
--theme-preview-active: var(
--system-accent-dark,
color-mix(in srgb, var(--system-accent, #2f6fdb), black 10%)
);
--theme-preview-toolbar: #18243a;
--theme-preview-panel: #18243a;
--theme-preview-swatch-border: rgba(29, 36, 51, 0.25);
}
Optional: styles/extra.css
Any other .css file in styles/ loads after the app’s stylesheets. Use it for platform tweaks the tokens can’t express, the way ui-dark moves the rail colour on Linux and Windows:
/* The nav rail sits on the window background on Linux and Windows. */
:root:where(:has(> body.platform-linux)),
:root:where(:has(> body.platform-win32)) {
--rail-background: var(--sidebar-background);
}
Keep these to :root token overrides where you can. Rules against the app’s class names break when markup changes.
Try it
- Put the
ui-harborfolder in<profile>/packages/, or use Install Theme… in the app menu (it runs thewindow:install-packagecommand). - Pick Harbor in Preferences > Appearance.
- Open Developer > Toggle Developer Tools, select
<html>and read the computed custom properties to check what each token resolved to. - Edit
tokens.css, then switch to another theme and back, or use Developer > Reload.
Check at least the thread list (unread, read, selected and focused rows), a message with quoted text, the composer, a menu, a modal and Preferences, in both a narrow and a split layout.
Following the system light or dark setting
The bundled ui-automatic theme has only a package.json with no styles/ and no scheme: the app switches between Light and Dark itself to follow the OS. A third-party theme can’t do that, so ship a light and a dark theme as two packages.
Tips
- Prefer tokens over extra rules. Extra CSS files in
styles/load after the app’s stylesheets, but rules against the app’s class names can break when the markup changes. - Check the thread list’s focused row: if your
--thread-list-focusedis pale, set--thread-list-focused-icon-whiten: 0so icons aren’t whitened. --rail-card-inset: 0joins the nav rail and sidebar into one column, as Darkside does.- Use the developer tools (Developer > Toggle Developer Tools) to inspect computed token values.
Mailspring themes
Themes built for Mailspring, or from the Mailspring theme starter, are LESS. Airpost still compiles them for compatibility until plugin API 2.0. A theme with styles/ui-variables.less and no styles/tokens.css gets its tokens from static/styles/compat/tokens.less, which maps the LESS variables to tokens. A minimal one looks like this:
my-less-theme/
├── package.json # same fields, "theme": "ui"
└── styles/
├── ui-variables.less
├── theme-colors.less # optional
└── index.less # optional extra rules
// styles/ui-variables.less
@import 'base/ui-variables'; // the defaults, so you only override what you change
@background-primary: #ffffff;
@background-secondary: #f3f5f8;
@text-color: #1d2433;
@text-color-subtle: fadeout(@text-color, 20%);
@accent-primary: #2f6fdb;
@border-color-divider: #e1e5ec;
@source-list-bg: #18243a;
@source-list-active-bg: rgba(255, 255, 255, 0.1);
@source-list-active-color: #ffffff;
@list-bg: @background-primary;
@list-focused-bg: #e8f0fd;
@border-radius-base: 4px;
The mapping includes, among others:
| LESS variable | Token |
|---|---|
@background-primary | --background |
@background-secondary | --secondary |
@text-color | --foreground |
@text-color-subtle | --subtle-foreground |
@accent-primary | --primary |
@border-color-divider | --border |
@input-bg | --control |
@component-active-color | --selected |
@source-list-bg | --sidebar-background |
@source-list-active-bg, @source-list-active-color | --sidebar-selected, --sidebar-selected-foreground |
@list-bg, @list-border | --thread-list-background, --thread-list-border |
@list-focused-bg, @list-focused-color | --thread-list-focused, --thread-list-focused-foreground |
@border-radius-base, @border-radius-small, @border-radius-large | --radius, --radius-sm, --radius-lg |
The full list is apps/desktop/static/styles/compat/tokens.less. Without a theme-colors.css, the previews read @source-list-bg, @background-primary, @accent-primary, @text-color and a few others from the theme’s variables. Some variables no longer reach the app’s styles, and Airpost’s own stylesheets are plain CSS, so a LESS theme can @import 'ui-variables' and 'ui-mixins' but nothing else from the app.
To port one, translate ui-variables.less into tokens.css with the table above and delete the LESS files. Don’t start a new theme in LESS.