Airpost
Themes and localization

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 --foreground also moves --subtle-foreground, --muted-foreground, --accent and so on, unless you set those too.
  • Custom properties resolve on the element that declares them, so declare yours on :root.
  • defaults.css loads before the theme’s tokens, so any theme rule on :root wins.
  • System accent. While “use system accent” is on, the app sets --system-accent and --system-accent-dark on :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

TokenMeaningDefault
--backgroundWindow and content background#ffffff
--foregroundBody text#231f20
--card / --card-foregroundRaised content, such as message cardsvar(--background) / var(--foreground)
--popover / --popover-foregroundMenus, popoversvar(--secondary) / var(--foreground)
--primary / --primary-foregroundAccent, and text on itvar(--system-accent, #1f70ec) / #ffffff
--secondary / --secondary-foregroundSecondary background#f4f6f9 / var(--foreground)
--mutedOff-white panels (composer action bar, attachments, calendar)#fdfdfd
--muted-foregroundDe-emphasised text--foreground at 60%
--accent / --accent-foregroundSubtle hover background--foreground at 5% / var(--foreground)
--destructive / --destructive-foregroundDestructive actions#d9534f / #ffffff
--borderDividers and borders--secondary mixed 90% with black
--inputInput and select bordersDerived from --background
--ringFocus ringvar(--primary)

Airpost additions:

TokenMeaningDefault
--subtle-foregroundSecondary text (sidebar items, snippets)--foreground at 85%
--heading-foregroundHeadings, toolbar text#3a3f47
--link / --link-hoverLinks#1f70ec / #1a5fcc
--control / --control-foregroundText inputs, selects, default buttons#ffffff / var(--foreground)
--control-borderButton outlinevar(--shadow-color)
--shadow-colorShadows and hairline bordersrgba(0, 0, 0, 0.15)

State tier

TokenMeaningDefault
--hoverHover backgroundvar(--accent)
--selected / --selected-foregroundStrong selection: focused row, active itemvar(--system-accent-dark, …) (10% darker --primary) / var(--background)
--unreadThe thread list’s unread dot#258fe1
--success / --warning / --danger / --infoStatus colours#5cb346 / #f0ad4e / var(--destructive) / #1c65d4

Surface tier

Each surface defaults to base or state tokens, so you only set what differs.

SurfaceTokens
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

TokenMeaningDefault
--radiusBase radius; the steps scale from it3px
--radius-sm / --radius-md / --radius-lg2px / var(--radius) / 5px
--font-sansUI font'Albert Sans', 'Helvetica', sans-serif; system-ui on Windows
--font-serif / --font-monoGeorgia stack / DejaVu Sans Mono stack
--font-headingvar(--font-sans)
--font-sizeBase UI text size14px
--densityPadding multiplier for kit components1
--row-height / --row-height-narrowThread list row height, wide and narrow36px / 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.