path: root/docs/themes.md

# Pardes themes

Pardes ships fifteen native palettes: six originals, six classic-inspired
adaptations and three contrast variants, designed for tags, text, search, diagnostics and embedded
terminals together. `orchard` is the initial theme.
Execute `Theme <name>` anywhere, or open `Themes` with `SPC t t` and select
a theme's command. Put the same command in your [startup configuration](config.md)
to keep a preference. `NextColor` cycles through the native themes first,
then `acme` and `lapis`, the [faithful ports](#faithful-ports), the legacy
`helix` and `dark`, and the imported palettes. `Themes` shows the same
order in sections: `Pardes themes`, one per ported family, `Legacy themes`
and `Imported themes (helix, zed)`; its navigation skips the section headings.
See the [Agave visual review](ui-review.md) for the original six-palette gallery.

| Theme | Character | Page | Accent |
| --- | --- | --- | --- |
| `orchard` | Near-black evergreen; bright leaf comments and plum syntax | `#0d1410` | `#adcc91` |
| `dusk` | Soft plum charcoal; copper comments and gentle text | `#39323b` | `#e4b39b` |
| `ink` | Pure black; bright, distinct signals and ice-blue comments | `#000000` | `#86d8ff` |
| `paper` | Neutral uncoated paper; graphite and teal | `#f5f3ed` | `#3c6b56` |
| `daybreak` | High contrast light; white and deep blue ink | `#ffffff` | `#075f91` |
| `atelier` | Acme homage; butter-yellow paper and blue-green tags | `#fffdeb` | `#3e7a68` |
| `forge` | Dark Plus-inspired near-black, blue and peach; slate-blue tags | `#0c0c0e` | `#a5c4ee` |
| `lagoon` | Softer Material-inspired slate; vivid sea-glass comments | `#34464c` | `#89c7b4` |
| `solarium` | Softer Solarized-inspired blue-green; golden comments and teal tags | `#173e45` | `#d5bc72` |
| `spectrum` | Monokai-inspired near-black and candy colors; golden comments | `#100e11` | `#ffd866` |
| `harvest` | Autumn-inspired near-black earth, ember and leaf green | `#100e0b` | `#cfba8b` |
| `clay` | Gruvbox-inspired near-black and earthy brights; amber comments | `#10100e` | `#8ec07c` |
| `forge_black` | Pure-black Forge; luminous text and cool slate tags | `#000000` | `#a5c4ee` |
| `forge_soft` | Neutral-slate Forge; gentler text, still vivid blue comments | `#35383e` | `#a5c4ee` |
| `orchard_black` | Pure-black Orchard; luminous garden ink and bright leaf comments | `#000000` | `#adcc91` |

The six adaptations retain recognizable classic syntax identities, but are
not exact ports. Their Acme influence is deliberate: quiet command strips,
thin boundaries, and a search surface
distinct from selection. Forge uses cool-neutral chrome instead of green
tints. Active pane and column tags use a restrained tone-on-tone shift, not
a light/dark inversion: dark palettes keep dark tags, and light palettes
keep light tags. A slight text lift and the focus marker retain the cue
without turning the entire command strip into a highlight.
The filename at the end of a pane's path uses a distinct hue at the same
perceived brightness as the tag text. The directory and commands keep
their usual foreground. Filename text meets the same contrast threshold on
both normal and active tag backgrounds.
Column drag grips use a separate accent from pane grips, with matching geometry.
Comments are colorful first-class text, while line numbers stay quiet;
the current line number gets a small color emphasis and bold weight, never a bright tag-colored
block. These are appearance changes only;
tag editing, commands and terminal interaction are unchanged.

Dark backgrounds make an explicit choice: near-black with bright text, or
the gentler slate/plum/blue-green of `forge_soft`, `dusk`, `lagoon` and
`solarium`. The softer group keeps body text around 5.5–6.7:1 contrast; the
near-black group exceeds 14:1. Try `Theme forge_black` and `Theme forge_soft`
back-to-back to compare the extremes without changing the syntax identity.
Light paper and the Acme homage remain available.

Their local references are `vendor/themes/dark_plus.toml`,
`material_oceanic.toml` (and its `material_deep_ocean.toml` parent),
`solarized_dark.toml`, `monokai_pro.toml`, `autumn.toml`, and the Gruvbox Dark
entry in `gruvbox.json`. The original imported themes remain selectable under
their existing names (one a [faithful port](#faithful-ports) now holds gains
`_helix`, as in `dracula_helix`); the adaptations have distinct Pardes names and do not
claim upstream affiliation. Existing vendor provenance and licenses remain
with those sources.

All fifteen palettes specify their own ANSI colors, so indexed terminal output
belongs to the same palette as the editor. Explicit true-color output can
still carry an application's own colors; the existing terminal `Filter`
command projects those colors through the theme. The older `dark` palette
continues to inherit the surrounding terminal's default background and text.

The native palettes keep normal text, syntax colors, comments,
diagnostics and ANSI foregrounds at a calculated sRGB contrast ratio of at
least 4.5:1 against the page. `ink` and `daybreak` raise that floor to 7:1.
Comments additionally stay above 5:1. Decorative line numbers sit between
2.5:1 and 4:1, with current numbers capped at 4.5:1; they deliberately do not
compete with source text. ANSI bright black is independent of the comment
color, so making comments vivid does not recolor gray terminal output.
Tag, active-tag, selection and search text are checked against their respective
surfaces at the same thresholds. Active/inactive tag backgrounds differ by
no more than 1.6:1, keeping focus changes quiet. ANSI black is exempt because applications
also use it as a background. These are palette checks, not a guarantee about
arbitrary terminal escape sequences, reversed colors or shader effects.

## Faithful ports

These are well-known themes taken as close to their originals as pardes can
draw them: every colour the original has (page, text, selection, syntax, line
numbers, diagnostics, terminal ANSI) is its own, read out of the original's
files, and each theme file cites the file and line of every value. The loose
adaptations above (`forge`, `solarium`, `spectrum`, ...) stay as they are.

pardes has one colour each for keywords, strings, numbers and comments, so a
theme that splits a kind (VS Code's control-flow keywords) keeps its main
one. A pane's tag is the original's window bar (vim's `StatusLine` and
`StatusLineNC`, emacs's `mode-line` and `mode-line-inactive`) or, in a tabbed
editor, its tab. What the original lacks (grips, a scroll column) comes from
its own palette. Where a chrome colour misses one of pardes's floors (rules
1.5:1 off the page, the focused tag 1.5:1 off the unfocused one on a dark
page and 1.25:1 on a light one, tag text 4.5:1), only that chrome colour
moves, just far enough, and the file's header says so. Text, syntax and ANSI
are never adjusted.

| Family | Themes | Source |
| --- | --- | --- |
| Visual Studio Code | `dark_plus` | VS Code 1.130.0 `extensions/theme-defaults/themes/dark_plus.json` and `dark_vs.json`; [microsoft/vscode](https://github.com/microsoft/vscode) 1.130.0 |
| Solarized | `solarized_dark`, `solarized_light` | [altercation/solarized](https://github.com/altercation/solarized); `~/05-genizah/solarized/vim-colors-solarized/colors/solarized.vim` |
| Dracula | `dracula`, `dracula_soft`, `alucard` | [dracula/dracula-theme](https://github.com/dracula/dracula-theme); [dracula/visual-studio-code](https://github.com/dracula/visual-studio-code) |
| Monokai | `monokai` | [download.sublimetext.com](https://download.sublimetext.com/Sublime%20Text%202.0.2%20x64.tar.bz2) |
| Monokai Pro | `monokai_pro`, `monokai_pro_classic`, `monokai_pro_machine`, `monokai_pro_octagon`, `monokai_pro_ristretto`, `monokai_pro_spectrum`, `monokai_pro_light`, `monokai_pro_light_sun` | [open-vsx.org](https://open-vsx.org/api/monokai/theme-monokai-pro-vscode/2.0.15/file/monokai.theme-monokai-pro-vscode-2.0.15.vsix) |
| Tokyo Night | `tokyonight_night`, `tokyonight_storm`, `tokyonight_moon`, `tokyonight_day` | [folke/tokyonight.nvim](https://github.com/folke/tokyonight.nvim) |
| Rosé Pine | `rose_pine`, `rose_pine_moon`, `rose_pine_dawn` | [rose-pine/palette](https://github.com/rose-pine/palette); [rose-pine/neovim](https://github.com/rose-pine/neovim) |
| Catppuccin | `catppuccin_latte`, `catppuccin_frappe`, `catppuccin_macchiato`, `catppuccin_mocha` | [catppuccin/palette](https://github.com/catppuccin/palette); [catppuccin/nvim](https://github.com/catppuccin/nvim) |
| Seoul256 | `seoul256_dark_233`, `seoul256_dark_234`, `seoul256_dark_235`, `seoul256_dark_236`, `seoul256_dark_237`, `seoul256_dark_238`, `seoul256_dark_239`, `seoul256_light_252`, `seoul256_light_253`, `seoul256_light_254`, `seoul256_light_255`, `seoul256_light_256` | [junegunn/seoul256.vim](https://github.com/junegunn/seoul256.vim) |
| Zenbones | `zenbones_light`, `zenbones_dark`, `neobones_light`, `neobones_dark`, `vimbones`, `forestbones_light`, `forestbones_dark`, `nordbones`, `rosebones_light`, `rosebones_dark`, `tokyobones_light`, `tokyobones_dark`, `seoulbones_light`, `seoulbones_dark`, `duckbones`, `zenburned`, `zenwritten_light`, `zenwritten_dark`, `kanagawabones` | [zenbones-theme/zenbones.nvim](https://github.com/zenbones-theme/zenbones.nvim) |
| Nord | `nord` | [nordtheme/nord](https://github.com/nordtheme/nord); [nordtheme/vim](https://github.com/nordtheme/vim); [nordtheme/visual-studio-code](https://github.com/nordtheme/visual-studio-code) |
| Ayu | `ayu_dark`, `ayu_mirage`, `ayu_light` | [ayu-theme/ayu-colors](https://github.com/ayu-theme/ayu-colors); [ayu-theme/vscode-ayu](https://github.com/ayu-theme/vscode-ayu) |
| Doom One | `doom_one`, `doom_one_light` | [doomemacs/themes](https://github.com/doomemacs/themes) |

## Make a theme your own

Run `DumpThemes` to export complete `.zon` files below the configuration
directory's `themes/builtin/`. Copy a native file to `themes/mine.zon`, change
its `.name`, and run:

```text
ThemeFile themes/mine.zon
```

On hosts with live document reload, saving a valid theme file updates it
immediately. An incomplete save keeps the last valid version. Selecting a
built-in theme stops the custom theme watch.

Pardes roles extend the original editor palette with independent choices
for its UI. Each value is an RGB triple, for example
`.search_bg = .{ 0x57, 0x47, 0x2a }`. New roles are optional and accept `null`,
so existing exported themes remain valid.

| Optional role | Purpose | When absent |
| --- | --- | --- |
| `tag_active_bg`, `tag_active_fg` | Focused pane tag surface and text; a surface closer than 1.25:1 to `tag_bg` is pushed further the way it already leans, as far as its text keeps its own contrast (or 4.5). Every dark native theme sets one | `tag_bg`, `tag_fg` |
| `tag_name_fg` | Filename or terminal `Tty` command tint | The corresponding normal or active tag foreground |
| `tag_active_name_fg` | Filename or terminal `Tty` tint in active tags | `tag_name_fg`, then the active tag foreground |
| `column_box` | Column grip while held, and its drag rail | `num` |
| `column_box_dim` | Column drag grip at rest, in every focus state | Equal mix of `column_box` and `tag_bg` |
| `border` | Quiet separators; one that stands off the page by less than 1.5:1 (a dark rule on a near-black page) is lifted toward the text to 1.6:1. A theme with no page is judged against #121212 | `scroll_track` |
| `empty_col` | A column with no pane, under its tag (acme: white) | `border`, as drawn |
| `lineno_active` | Restrained current line number foreground | `lineno` |
| `search_bg`, `search_fg` | Search matches, independent of selection | `sel_bg`, `sel_fg` |
| `diagnostic_error` | Error text | `fg`, or `tag_fg` for an inherited foreground |
| `diagnostic_warning` | Warning text | Same foreground fallback |
| `diagnostic_info` | Informational diagnostic text | Same foreground fallback |
| `diagnostic_hint` | Hint text | Same foreground fallback |
| `tag_sel_bg` | A tag's selection ground | `sel_bg` |
| `sweep_bg`, `sweep_fg` | Three triples each: the select, exec and look sweeps' ground and ink | `sel_bg` tinted toward `kw`, `str` and `num`, in `sel_fg` |
| `tag_rule` | The one-pixel rule between a pane's tag and its body, quieter than the `rule_px` rules between panes and columns | Halfway between `tag_bg` and the page the shell draws |
| `rule_px` | Pixel shells: the width of the rules between columns, between panes stacked in a column, and under the workspace and column tags, in `border` (the rule between a tag and its body is always one pixel), in logical pixels: doubled on a 2x display, as acme scales its Border | 2 |
| `box_border`, `box_dirty` | The grip is acme's button: `box` filled when focused, else a two-pixel ring of `box_border` round the tag's ground; `box_dirty` fills it inside either ring while its file is unsaved (a grid, which has no ring, shows a bold `*` on `box_dirty` in the grip's second cell) | `box_dim`; `diagnostic_warning`, then `num` |
| `rail_px` | Pixel shells: the scroll column's width, the grip's button over the scrollbar (thumb a pixel narrower), in pixels at a 17px tagline, scaled with it | 12, acme's Scrollwid |
| `decor` | Pixel shells: a theme's ornament, drawn inside the chrome it has (lapis's): `page_dots` (a dot grid on the page's own ground, `page_dot_alpha` strong every `page_dot_px`), `rail_checker` (a checker in the scroll track, squares of `rail_checker_px`), `tag_border`, `tag_shadow`, `tag_stripe` (every tag a raised plaque inside its own band: a `tag_border_px` frame round its text and a hard `tag_shadow_px` shadow down and right, both inside the band's rows and columns; the focused pane's plaque striped `tag_stripe_px` with its words on plates of the tag's ground; column and workspace tags a quieter one; opaque windows only) and `title_shadow` (the file name's offset shadow, `title_shadow_px`), sizes in logical pixels. None of it touches a focus indicator | none |

Native palettes give filenames a distinct hue at approximately the same
brightness as the surrounding tag text. This also applies to output names
such as `+Search`. Terminal tags instead tint `Tty`, the first builtin after
the path. Directory paths and the other commands retain the regular tag color.

These colors are shared by the GUI and TTY. Tags and their active tint retain
the same text, command execution, drag targets and focus behavior. Selection
and search have separate palette roles because they communicate different
states. Theme changes use the existing chrome transition; body and terminal
colors switch directly so syntax and ANSI content stay coherent.

`FocusTint` toggles the focused pane's tag tint, which is on by default.
`SyntaxBold` toggles bold syntax keywords, which are off by default. Both
commands take no argument, work in GUI and TTY, and report their states in
`Config`. Use them in the startup configuration to reverse the defaults.

The original required roles remain unchanged: nullable `bg` and `fg`,
`sel_bg`, `sel_fg`, `tag_bg`, `tag_fg`, `box`, `box_dim`, `kw`, `str`, `num`,
`comment`, `lineno`, `scroll_track`, `scroll_thumb`, and a nullable 16-entry
`palette`. `ThemeFile` loads a complete theme, with no inheritance or partial
override syntax. The exported native files are the easiest starting point.