1---2title: "Themes"3sidebar_position: 24---56# Themes78A theme is a terminal color scheme: the 16 ANSI colors plus a background,9a foreground and a selection color, the same shape Ghostty, kitty, iTerm2,10Alacritty and VHS themes have. 012 has no theme format of its own to learn:11any scheme works, and so does any Ghostty theme file.1213```14# ~/.config/012/config15theme = terminal # the default16theme = Dracula # one scheme17theme = light:Catppuccin Latte,dark:Catppuccin Mocha # follow the terminal18```1920- **`terminal`** (the default) draws with the terminal's own palette, as21 ANSI color numbers, with a dark and a light variant picked from the22 terminal's background. It looks the way your terminal is set up.23- **Any other name** is a color scheme. 012 draws its roles in the24 scheme's colors (true color), fills the whole screen with the scheme's25 background, and draws the menu bar, the column headers and the status26 line as solid bands, in the manner of 1-2-3 and classic terminal27 programs. The terminal's own palette is never changed.28- **`high-contrast`** is white on black on a dark terminal and black on29 white on a light one, switching when the terminal does, with every30 role at WCAG AAA contrast (see [High contrast](#high-contrast)).31- **`light:A,dark:B`** picks A on a light terminal and B on a dark one,32 and switches when the terminal does (for example with the system's33 appearance, in terminals that report it).3435At startup the screen stays blank until the terminal says its36background, so a light terminal never shows a frame in dark colors,37even over SSH; a terminal that doesn't answer is waited for at most38half a second.3940File > Settings > Theme opens a picker: type to search the names. A41search starting with "dark" or "light" lists only the schemes of that42kind (by `meta.isDark`, so "light" leaves out dark schemes such as Bright43Lights), the rest of it searching their names: "light sol" finds44Solarized Light. The highlighted theme is drawn live, Enter keeps it and45writes `theme = ...` to the config file, and Esc goes back to the theme you46had. With a `light:`/`dark:` pair, the picker changes the one in use.47In terminals that say when a key is let go ([Keys the terminal has to48tell apart](../reference/keys.md#keys-the-terminal-has-to-tell-apart)),49holding Space before typing a search hides the list to show the whole50sheet in the highlighted theme, until Space is let go.51`012 config themes` lists every theme, with a `*` on the current one.52535455## Built-in schemes5657012 embeds the 348 schemes of [VHS](https://github.com/charmbracelet/vhs)58(Dracula, Nord, Gruvbox, Catppuccin, Solarized, Tokyo Night, One Dark,59Rose Pine and hundreds more), so names are the ones VHS's `Set Theme`60takes, plus **1-2-3 Classic**: CGA colors on a blue screen. Names match61without regard to case, and then without regard to spaces, hyphens and62underscores, so `tokyo-night` finds `TokyoNight`.6364## High contrast6566`theme = high-contrast` draws with two built-in schemes, **High Contrast67Dark** and **High Contrast Light**, picked by the terminal's background;68name one of them (`theme = high-contrast-light`) to keep it. They hold69every role to WCAG AAA rather than AA: 7:1 for all text, hints and70muted text included, and 4.5:1 for lines, borders, chart axes and71unavailable menu items. The pointer is black on cyan, the selection72white on blue, errors a light red on black (a dark red on white).7374States never rest on color alone in any theme: each also shows as75text, a glyph or an attribute such as reverse video or an underline76([Reading without color](../contributing/ux.md#reading-without-color)).7778## Your own schemes7980Put a file in the `themes` directory next to the config file81(`~/.config/012/themes/` on Linux; `012 config path` shows where the82config is) and use its file name as the theme. A file with a built-in's83name replaces it. Three formats are read:8485- **Ghostty** (copy any Ghostty theme unchanged):8687 ```88 palette = 0=#1d1f2189 palette = 1=#cc666690 # ... through 1591 background = #1d1f2192 foreground = #c5c8c693 selection-background = #373b4194 ```9596- **kitty**: `color0 #1d1f21` through `color15`, `background`,97 `foreground` and `selection_background`.98- **VHS JSON**: one scheme or a list, with `black` ... `brightWhite`,99 `background`, `foreground`, `selection` and `meta.isDark` (a `.json`100 file; `purple` and `selectionBackground` are accepted too).101102A scheme needs a background and a foreground; ANSI colors it leaves out103are xterm's. Other keys (fonts, cursor colors) are ignored.104105## How roles get their colors106107Every role in `internal/ui/theme` (the cell pointer, selection, headers,108menus, errors, links, chart series and so on) is defined on the ANSI109colors and the background and foreground: the pointer is black on cyan,110headers are bright white on bright black (black on white on light111terminals), errors are red. The terminal theme sends those color numbers;112a scheme replaces each with its own color. Then, so every scheme reads113well:114115- the selection uses the scheme's selection color, when it has one;116- the menu bar and status line are the background moved 12% toward the117 text color; the column header row is filled with the header color;118- a background role too close to the screen's background is moved apart;119- text below its contrast minimum against its background (WCAG 4.5:1 for120 text, 3:1 for hints, lines and chart axes, 2:1 for unavailable items;121 the high-contrast schemes' AAA minimums above) is moved toward the122 scheme's text color, or toward black or white, just far enough to123 reach it.124125A test runs every built-in scheme through this and checks those minimums126for cell text, text on the bars, the selection, the headers and every127other role (`TestEveryThemeReadable`, and `TestHighContrast` for AAA). Charts, as text and as kitty128images, use the scheme's colors too.129130Conditional formats ([Conditional formatting and data validation](../sheets/rules.md#conditional-formatting)) name131their colors (red, yellow, green, cyan, blue, magenta) rather than132giving RGB, and each is an ANSI slot, so they follow the theme too: a133text color is the slot on the cell (`RuleText`), a fill the slot as a134background with black or bright white text, whichever reads better135(`RuleFill`), and a text color on a fill (`RuleOn`) takes the fill's136ink where it wouldn't read on it. These roles are corrected and checked137like the others, and the terminal theme's are checked against the two138reference palettes. A color scale blends the slots of its points, the139scheme's colors or the terminal's own (asked for with OSC 4 at startup,140xterm's when it doesn't answer), in 32 shades between two points; text141on a shade is the scheme's text or background color (the terminal's142bright white or black), whichever reads better, or pure black or white143where neither reaches 4.5:1. A test checks the shades of every pair of144colors under every scheme.145146The roles for the bars are `MenuBarRow`, `FormulaBarRow`, `ContextRow`,147`ColumnHeaderRow` and `StatusBarRow` (a background and a text color for148the whole line, out to the terminal's edge, under overlays too), with149`RowHeader` for the row numbers and `Screen` for everything else. The150terminal theme leaves them empty, so it looks as it always has.151152## Credits153154The built-in schemes are VHS's `themes.json` (MIT License, Copyright (c)1552022-2023 Charmbracelet, Inc.; see [NOTICE](../../NOTICE)), which credits156each scheme's authors in its `meta.credits`. The contrast correction is157adapted from the theme package of puzzletea, by the same author.