Themes

A theme is a JSON file in the themes folder. Changes to the file apply as soon as you save it.

Choosing a theme

Pick a theme in SettingsAppearanceTheme. For a theme with variants, such as Catppuccin, click its name to pick a variant. In settings.json, set appearance.theme to the theme's id.

With Adaptive theme on, only System, Dark and Light are available. It is off by default.

Community themes

Browse themes people shared on the themes page, or open it with SettingsAppearanceThemeExplore community themes. Press Install on a theme and Sonora shows a preview and asks before adding it to your themes folder. A theme with variants installs with all of them. Download saves the file, or a zip for a theme with variants, to put in the folder yourself.

To remove a theme from your themes folder, press the trash button on its card in SettingsAppearanceTheme. To share your own, see Writing a theme and submit it.

The themes folder

Open it with SettingsAppearanceThemeOpen folder. It is 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 id is the file's path in the themes folder without .json: fjord.json is fjord, catppuccin/mocha.json is catppuccin/mocha. The ids system, dark and light are reserved.

A theme file has four keys: name, author, version and theme. The version must be 1.

themes/fjord.json
{
  "name": "Fjord",
  "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 #. Tokens you leave out use the Dark theme's colors.

An unknown key or an invalid color makes the file invalid. If an edit breaks a theme that was already loaded, its last valid version stays in use and the error goes to the log.

Variants

Files in a subfolder of the themes folder form one theme with a variant per file. Only one level of subfolders is read, and symlinks are skipped.

Folder layout
themes/
  fjord/
    night.json    "name": "Fjord Night"
    day.json      "name": "Fjord Day"

The words all variant names start with become the theme's name, and the rest of each name becomes the variant's. The layout above is a theme called Fjord with the variants Night and Day.

Changing a built-in theme

A theme file with a built-in theme's id replaces it. Copy a file from assets/themes in Sonora's repository, for example to themes/catppuccin/mocha.json, and edit it.

Color tokens

Surfaces and textbackground foreground muted muted_foreground border secondary secondary_hover secondary_active popover popover_foreground overlay overlay_foreground
Accentsprimary primary_foreground primary_hover danger danger_foreground danger_hover progress_bar selection
Sidebar and title barsidebar sidebar_accent sidebar_border title_bar_border
Tablestable_head table_head_foreground table_row_border table_hover table_active table_active_border

Changing a single color

To change a color or two, add theme_overrides to the appearance block in settings.json instead of writing a file. Overrides apply on top of any theme, including the adaptive tint.

settings.json
"appearance": {
  "theme": "catppuccin/mocha",
  "theme_overrides": {
    "primary": "#f5a97f",
    "primary_foreground": "#1e1e2e",
    "progress_bar": "#f5a97f"
  }
}