diff options
Diffstat (limited to 'docs/themes.md')
| -rw-r--r-- | docs/themes.md | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/docs/themes.md b/docs/themes.md new file mode 100644 index 00000000..7d71d0dd --- /dev/null +++ b/docs/themes.md @@ -0,0 +1,124 @@ +# 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. +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` | +| `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 | + +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. |