Themes

The sophonz theme file — iTerm2's color scheme keys plus the colors of the app around the terminal — its schema, every key, the themes to download, and how to bring one in.

A theme is a JSON file that colors the terminal and, if you like, the app around it: the sidebar, the tabs, the agent chart, menus and dialogs. The file format, theme v1, is iTerm2's color scheme with a few keys added. An iTerm2 scheme written as JSON is already a valid theme, and an .itermcolors file is read as it is.

Themes you bring in are kept on your account (up to 16). Every app signed in to it lists them after the built-in four. The theme in use is one of the terminal settings the account keeps, which the desktop app follows from 0.1.27 and the browser terminal from st 0.3.79.

Download a theme

Each file has terminal colors and app colors. Download one and bring it in, or use it as a start for your own.

sophonz and sophonz Light are Obsidian's default themes, read from Obsidian 1.8.4, so a vault opened in the app looks like the app around it. They are the only themes the Appearance setting switches between: with sophonz picked and Appearance light (or System on a light system), the app draws sophonz Light. Every other theme keeps its own look.

The terminal colors of the Dracula, Nord, Tokyo Night, Catppuccin, Gruvbox and Solarized files come from iTerm2-Color-Schemes (MIT). The app colors are taken from each theme's own palette.

Bring one in

In the desktop app or the browser terminal, open Settings, find Terminal theme, and choose + Import…. You can also drop files on that row. Several at once are fine, and the last one is picked.

• Accepted files: theme JSON (this page), iTerm2's .itermcolors files as iterm2colorschemes.com hands them out, and the collection's Windows Terminal JSON.
• A bad file: it is refused with the reason, and nothing changes. For example: "Backgrund Color" is not a key of a theme (theme-v1) or missing Ansi 7 Color.
• The same name again: a theme whose name gives the same id replaces the one you had.
• Removing one: point at its swatch and click ×. If it was in use, the terminal goes back to sophonz.

The file format

{
  "$schema": "https://www.sophonz.io/schemas/theme-v1.json",
  "format": "sophonz-theme",
  "version": 1,
  "name": "Night Shift",
  "author": "you",
  "appearance": "dark",
 
  "Ansi 0 Color": "#21222c",
  "Ansi 1 Color": "#ff5555",
  "…": "Ansi 2 Color through Ansi 15 Color the same way",
  "Background Color": "#282a36",
  "Foreground Color": "#f8f8f2",
  "Cursor Color": "#f8f8f2",
  "Selection Color": "#44475a",
 
  "UI Sidebar Color": "#21222c",
  "UI Accent Color": "#bd93f9"
}

(The "…" line is not a key; a real file lists all sixteen ANSI colors.)

About the file

Terminal colors

The sixteen ANSI colors, the background and the foreground are required.

Colors 16–255 of the 256-color palette are xterm's standard cube and greys for every theme.

App colors

Every UI … Color is optional. With none, the desktop app (0.2.0 and later) makes the app colors from the terminal's: the page and sidebar from the background, the panel, border and hover from the text over it (5, 14 and 8%), muted text at 62%, the selection from the terminal's, and the accent, asking, success and error colors from ANSI 4, 3, 2 and 1. Before 0.2.0, a theme with none keeps the app's own light or dark look. With any of them, the theme's appearance sets the app's look: buttons and inputs come out light or dark to match, and the Appearance setting stands aside while the theme is in use. Colors the theme does not give keep the app's own values for that look (from desktop 0.2.0, they are made from the terminal colors as above).

iTerm2's other keys

Link Color, Badge Color, Tab Color, Cursor Guide Color, Match Background Color, Underline Color, Active Pane Border Color and IME Cursor Color are valid, so iTerm2 schemes pass as they are. They are not drawn or kept.

iTerm2 3.5 writes some colors twice, for its light and dark modes: Background Color (Dark), Background Color (Light) and so on. Both are valid for every terminal and iTerm2 key, but not for the UI keys. The plain key wins, then the (Dark) one. (Light) is not read.

Any other key makes the file invalid.

Color values

Every color is either #rrggbb or iTerm2's dictionary:

"Background Color": {
  "Red Component": 0.157,
  "Green Component": 0.165,
  "Blue Component": 0.212,
  "Alpha Component": 1,
  "Color Space": "sRGB"
}

Limits and validation

• The schema: theme-v1.json is a JSON Schema (2020-12). Every app checks theme JSON against the same rules (desktop app 0.1.29, st 0.3.81 and later). The keys, the values and the required colors are checked before anything is kept.
• Size and number: a file may be at most 256 KB. An account keeps 16 themes.
• The id: custom- followed by the name in lowercase letters, digits and dashes, at most 40 characters. A name with none of those, such as one all in Hangul, gets custom-theme.
• What is kept: the account keeps id, name, appearance and the colors above as #rrggbb. iTerm2's other keys, author and description are left out.
• Other formats: .itermcolors (Apple property list) and Windows Terminal JSON (black … brightWhite, background, foreground, cursorColor, selectionBackground) are read by their own rules, not against this schema. They have no app colors.

Editors validate it too

With the $schema line at the top, VS Code and other editors with JSON Schema support check the file as you type. They mark a misspelt key or a bad color, and suggest every key with its description.