Custom themes

A theme is one JSON file in the themes folder. Themes support hot reloading, and Sonora reflects the changes on each save.

The themes folder

SettingsAppearanceThemeOpen folder opens it. It is located next to the settings file.

Linux	`~/.config/sonora/themes/`
Flatpak	`~/.var/app/io.github.nolight132.sonora/config/sonora/themes/`
macOS	`~/Library/Application Support/sonora/themes/`
Windows	`%APPDATA%\sonora\themes\`

Writing a theme

The file name becomes the theme's id, so nord.json is nord. Built-in names like dark, light and midnight are taken.

The file needs four keys to be a valid theme: name, author, version and theme. The version must be 1 and is only there for future compatibility. If this changes, the current correct value will be reflected here.

themes/nord.json

{
  "name": "Nord",
  "author": "Your Name",
  "version": 1,
  "theme": {
    "background": "#2e3440",
    "foreground": "#eceff4",
    "sidebar": "#2b303b",
    "popover": "#3b4252",
    "secondary": "#3b4252",
    "muted": "#434c5e",
    "muted_foreground": "#a3acb9",
    "border": "#4c566a66",
    "primary": "#88c0d0",
    "primary_foreground": "#2e3440",
    "progress_bar": "#88c0d0",
    "selection": "#5e81ac",
    "table_active": "#5e81ac33",
    "table_active_border": "#88c0d0"
  }
}

Colors are hex, RRGGBB or RRGGBBAA, with or without the #. Unset values currently default to a dark theme. Do not rely on this behavior. It may change in the future.

Save as UTF-8; a UTF-8 byte order mark is accepted since v0.42.0. Only the four top-level keys and the color tokens below are allowed. An unknown key or invalid color rejects the file. If a previously loaded theme is edited into an invalid file, Sonora keeps its last valid version and reports the error in the log.

Color tokens

Surfaces and text	`background` `foreground` `muted` `muted_foreground` `border` `secondary` `secondary_hover` `secondary_active` `popover` `popover_foreground` `overlay` `overlay_foreground`
Accents	`primary` `primary_foreground` `primary_hover` `danger` `danger_foreground` `danger_hover` `progress_bar` `selection`
Sidebar and title bar	`sidebar` `sidebar_accent` `sidebar_border` `title_bar_border`
Tables	`table_head` `table_head_foreground` `table_row_border` `table_hover` `table_active` `table_active_border`

Using it

Your themes show up at the bottom of the theme picker below the built-in themes. Setting appearance.theme to the id in settings.json works too.

Having Adaptive theme on prevents using any custom themes. Adaptive colors are also forced in fullscreen unless Ambient background is off.

Tweaking a built-in theme

Only want to change a color or two? Skip the file and add theme_overrides to the appearance block in settings.json. It works on any theme, built-in ones included, and beats the adaptive tint.

settings.json

"appearance": {
  "theme": "dark",
  "theme_overrides": {
    "primary": "#f5a97f",
    "primary_foreground": "#2e3440",
    "progress_bar": "#88c0d0"
  }
}