diff options
Diffstat (limited to 'runtime/doc')
| -rw-r--r-- | runtime/doc/dev_theme.txt | 103 | ||||
| -rw-r--r-- | runtime/doc/news.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 2 |
3 files changed, 108 insertions, 0 deletions
diff --git a/runtime/doc/dev_theme.txt b/runtime/doc/dev_theme.txt new file mode 100644 index 0000000000..04ec3f293c --- /dev/null +++ b/runtime/doc/dev_theme.txt @@ -0,0 +1,103 @@ +*dev_theme.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Nvim theme style guide *dev-theme* + +This is style guide for developers working on Nvim's default color scheme. + +License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/ + + Type |gO| to see the table of contents. + +============================================================================== +Design + +- Be "Neovim branded", i.e. have mostly "green-blue" feel plus one or two + colors reserved for very occasional user attention. + +- Be extra minimal for 'notermguicolors' (256 colors) while allowing a bit + more shades when 'termguicolors' is set (true colors). + +- Be accessible, i.e. have high enough contrast ratio (as defined in + https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef). + This means to have value at least 7 for |hl-Normal| and 4.5 for some common + cases (|hl-Visual|, `Comment` with set 'cursorline', colored syntax, `Diff*`, + |hl-Search|). + +- Be suitable for dark and light backgrounds via exchange of dark and light + palettes. + +- Be usable, i.e. provide enough visual feedback for common objects. + + +============================================================================== +Palettes + +- There are two separate palettes: dark and light. They all contain the same + set of colors exported as `NvimDark*` and `NvimLight*` colors respectively. + +- The dark palette is used for background in the dark color scheme and for + foreground in the light color scheme; and vice versa. This introduces + recognizable visual system without too standing out. + +- Actual computation of palettes should be done in a perceptually uniform + color space. Oklch is a good choice. + +- Each palette has the following colors (descriptions are for dark background; + reverse for light one): + + - Four shades of "colored" greys for general UI. In 256 colors they are + exact greys; in true colors they are shades of "cold" grey. + + - Dark ones (from darkest to lightest) are reserved as background for + |hl-NormalFloat| (considered as "black"), |hl-Normal| (background), + |hl-CursorLine|, |hl-Visual|. + + - Light ones (also from darkest to lightest) are reserved for + `Comment`, |hl-StatusLine|/|hl-TabLine|, |hl-Normal| (foreground), + and color considered as "white". + +- Six colors to provide enough terminal colors: red, yellow, green, cyan, + blue, magenta. + They should have (reasonably) similar lightness and chroma to make them + visually coherent. Lightness should be as equal to the palette's basic grey + (which is used for |hl-Normal|) as possible. They should have (reasonably) + different hues to make them visually separable. + +- Each palette color should have a 256 colors variant with closest color + computed based on the perceptually uniform distance measure. + + +============================================================================== +Highlight groups + +Use: + +- Grey shades for general UI according to their design. + +- Bold text for keywords (`Statement` highlight group). This is an important + choice to increase accessibility for people with color deficiencies, as it + doesn't rely on actual color. + +- Green for strings, |hl-DiffAdd| (as background), |hl-DiagnosticOk|, and some + minor text UI elements. + +- Cyan as main syntax color, i.e. for function usage (`Function` highlight + group), |hl-DiffText|, |hl-DiagnosticInfo|, and some minor text UI elements. + +- Red to generally mean high user attention, i.e. errors; in particular for + |hl-ErrorMsg|, |hl-DiffDelete|, |hl-DiagnosticError|. + +- Yellow very sparingly only with true colors to mean mild user attention, + i.e. warnings. That is, |hl-DiagnosticWarn| and |hl-WarningMsg|. + +- Blue very sparingly only with true colors as |hl-DiagnosticHint| and some + additional important syntax group (like `Identifier`). + +- Magenta very carefully (if at all). + + + vim:tw=78:ts=8:et:ft=help:norl: diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 825e5ba41f..f5b41f38a6 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -95,6 +95,9 @@ The following changes may require adaptations in user config or plugins. • Legacy and extmark signs are displayed and listed with the same priority: line number -> priority -> sign id -> recently placed +• Default color scheme has been updated to be "Neovim branded" and accessible. + Use `:colorscheme vim` to revert to the old legacy color scheme. + ============================================================================== BREAKING CHANGES IN HEAD *news-breaking-dev* diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index cf9b3cf0e5..f6dfe3b14a 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -30,6 +30,8 @@ Defaults *nvim-defaults* ":filetype off" to |init.vim|. - Syntax highlighting is enabled by default. This can be disabled by adding ":syntax off" to |init.vim|. +- Default color scheme has been updated. This can be reversed by adding + ":colorscheme vim" to |init.vim|. - 'autoindent' is enabled - 'autoread' is enabled (works in all UIs, including terminal) |