Quick links: help overview · quick reference · user manual toc · reference manual toc
Go to keyword (shortcut: k)
Site search (shortcut: s)
dev_theme.txt          Nvim


                            NVIM REFERENCE MANUAL


Nvim colorscheme guidelines                                   dev-theme

Style guidelines for developing Nvim's default colorscheme.

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 oriented for 'termguicolors' (true colors) while being extra minimal for
  'notermguicolors' (16 colors) as fallback.
- 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 "cold" greys for general UI.
        - 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.
- For 16 colors:
    - Greys are not used and are replaced with the foreground and background
      colors of the terminal emulator.
    - Non-grey colors fall back to terminal colors as ordered in ANSI codes
      (https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit),
      that is red (1, 9), green (2, 10), yellow (3, 11), blue (4, 12),
      magenta (5, 13), cyan (6, 14).
      To increase contrast, colors 1-6 are used for light background and 9-14
      for dark background.

==============================================================================
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 to mean mild user attention, i.e. warnings. That is,
  hl-DiagnosticWarn and hl-WarningMsg.
- Blue very sparingly as hl-DiagnosticHint and some additional important
  syntax group (like Identifier).
- Magenta very carefully (if at all).

In case of 16 colors:

- Rely on the assumption "Background color can be used as background; other
  colors can be used as foreground". This means that in any
  foreground/background combination there should be background and one
  non-background color.
- Use 0 (black) or 15 (bright white) as foreground for non-grey background,
  depending on whether normal background is light or dark.

 vim:tw=78:ts=8:et:ft=help:norl:


Quick links: help overview · quick reference · user manual toc · reference manual toc