diff options
Diffstat (limited to 'docs/themes.md')
| -rw-r--r-- | docs/themes.md | 186 |
1 files changed, 0 insertions, 186 deletions
diff --git a/docs/themes.md b/docs/themes.md deleted file mode 100644 index db6349c4..00000000 --- a/docs/themes.md +++ /dev/null @@ -1,186 +0,0 @@ -# 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`, `lapis` and `lapis_plain`, 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. -`lapis` draws its ornament in the GUI; `lapis_plain` is the same theme on -flat grounds (no dot grid under the text, no stripes behind the focused -tag), with lapis's framed and shadowed tags and its file-name shadow. -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 -`DumpConfig`. 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. |