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 `ThemeSel` 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 the retained `helix`, `dark` and `acme` themes and imported palettes.
`ThemeSel` groups the new palettes under `Pardes themes`, followed by
`Legacy and imported themes`; 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 subtle accent tint, mixed
from the tag text and each palette's accent. The directory and commands keep
their usual foreground. Filename text meets the same contrast threshold on
both normal and active tag backgrounds.
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; 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.

## 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 | `tag_bg`, `tag_fg` |
| `tag_name_fg` | Filename at the end of the pane's path, on normal and active tags | The corresponding normal or active tag foreground |
| `border` | Quiet separators | `scroll_track` |
| `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 |

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.