neovim

Neovim text editor
git clone https://git.dasho.dev/neovim.git
Log | Files | Refs | README

dev_theme.txt (4576B)

      1 *dev_theme.txt*          Nvim
      2 
      3 
      4                            NVIM REFERENCE MANUAL
      5 
      6 
      7 Nvim colorscheme guidelines                                   *dev-theme*
      8 
      9 Style guidelines for developing Nvim's default colorscheme.
     10 
     11 License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/
     12 
     13                                      Type |gO| to see the table of contents.
     14 
     15 ==============================================================================
     16 Design
     17 
     18 - Be "Neovim branded", i.e. have mostly "green-blue" feel plus one or two
     19  colors reserved for very occasional user attention.
     20 - Be oriented for 'termguicolors' (true colors) while being extra minimal for
     21  'notermguicolors' (16 colors) as fallback.
     22 - Be accessible, i.e. have high enough contrast ratio (as defined in
     23  https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef).
     24  This means to have value at least 7 for |hl-Normal| and 4.5 for some common
     25  cases (|hl-Visual|, `Comment` with set 'cursorline', colored syntax, `Diff*`,
     26  |hl-Search|).
     27 - Be suitable for dark and light backgrounds via exchange of dark and light
     28  palettes.
     29 - Be usable, i.e. provide enough visual feedback for common objects.
     30 
     31 
     32 ==============================================================================
     33 Palettes
     34 
     35 - There are two separate palettes: dark and light. They all contain the same
     36  set of colors exported as `NvimDark*` and `NvimLight*` colors respectively.
     37 - The dark palette is used for background in the dark color scheme and for
     38  foreground in the light color scheme; and vice versa. This introduces
     39  recognizable visual system without too standing out.
     40 - Actual computation of palettes should be done in a perceptually uniform
     41  color space. Oklch is a good choice.
     42 - Each palette has the following colors (descriptions are for dark background;
     43  reverse for light one):
     44    - Four shades of colored "cold" greys for general UI.
     45        - Dark ones (from darkest to lightest) are reserved as background for
     46          |hl-NormalFloat| (considered as "black"), |hl-Normal| (background),
     47          |hl-CursorLine|, |hl-Visual|.
     48        - Light ones (also from darkest to lightest) are reserved for
     49          `Comment`, |hl-StatusLine|/|hl-TabLine|, |hl-Normal| (foreground),
     50          and color considered as "white".
     51 - Six colors to provide enough terminal colors: red, yellow, green, cyan,
     52  blue, magenta.
     53  They should have (reasonably) similar lightness and chroma to make them
     54  visually coherent. Lightness should be as equal to the palette's basic grey
     55  (which is used for |hl-Normal|) as possible. They should have (reasonably)
     56  different hues to make them visually separable.
     57 - For 16 colors:
     58    - Greys are not used and are replaced with the foreground and background
     59      colors of the terminal emulator.
     60    - Non-grey colors fall back to terminal colors as ordered in ANSI codes
     61      (https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit),
     62      that is red (1, 9), green (2, 10), yellow (3, 11), blue (4, 12),
     63      magenta (5, 13), cyan (6, 14).
     64      To increase contrast, colors 1-6 are used for light background and 9-14
     65      for dark background.
     66 
     67 ==============================================================================
     68 Highlight groups
     69 
     70 Use:
     71 
     72 - Grey shades for general UI according to their design.
     73 - Bold text for keywords (`Statement` highlight group). This is an important
     74  choice to increase accessibility for people with color deficiencies, as it
     75  doesn't rely on actual color.
     76 - Green for strings, |hl-DiffAdd| (as background), |hl-DiagnosticOk|, and some
     77  minor text UI elements.
     78 - Cyan as main syntax color, i.e. for function usage (`Function` highlight
     79  group), |hl-DiffText|, |hl-DiagnosticInfo|, and some minor text UI elements.
     80 - Red to generally mean high user attention, i.e. errors; in particular for
     81  |hl-ErrorMsg|, |hl-DiffDelete|, |hl-DiagnosticError|.
     82 - Yellow very sparingly to mean mild user attention, i.e. warnings. That is,
     83  |hl-DiagnosticWarn| and |hl-WarningMsg|.
     84 - Blue very sparingly as |hl-DiagnosticHint| and some additional important
     85  syntax group (like `Identifier`).
     86 - Magenta very carefully (if at all).
     87 
     88 In case of 16 colors:
     89 
     90 - Rely on the assumption "Background color can be used as background; other
     91  colors can be used as foreground". This means that in any
     92  foreground/background combination there should be background and one
     93  non-background color.
     94 - Use 0 (black) or 15 (bright white) as foreground for non-grey background,
     95  depending on whether normal background is light or dark.
     96 
     97 vim:tw=78:ts=8:et:ft=help:norl: