Airpost
Themes and localization

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:

  • --primary and --selected go through --system-accent and --system-accent-dark, so “use system accent” in Preferences > Appearance still works.
  • The focused row is pale, so --thread-list-focused-icon-whiten: 0 keeps icons dark on it.
  • --rail-card-inset: 0 joins 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 plain px lengths, 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

  1. Put the ui-harbor folder in <profile>/packages/, or use Install Theme… in the app menu (it runs the window:install-package command).
  2. Pick Harbor in Preferences > Appearance.
  3. Open Developer > Toggle Developer Tools, select <html> and read the computed custom properties to check what each token resolved to.
  4. 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-focused is pale, set --thread-list-focused-icon-whiten: 0 so icons aren’t whitened.
  • --rail-card-inset: 0 joins 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 variableToken
@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.