feat(highlight): tweak default color scheme

Problem: Updating default color scheme produced some feedback.

Solution: Address the feedback.

Outline of the changes:

- Colors `Grey1` and `Grey2` are made a little bit more extreme (dark -
  darker, light - lighter) to increase overall contrast.

- `gui` colors are treated as base with `cterm` colors falling back to
  using 0-15 colors which come from terminal emulator.

- Update highlight group definition to not include attribute definition
  if it is intended to staty uncolored.

- Tweak some specific highlight groups.

- Add a list of Neovim specific highlight groups which are now defined
  differently in a breaking way.

- Minor tweaks in several other places related to default color scheme.

6 files changed, 63 insertions, 23 deletions

diff --git a/runtime/colors/default.vim b/runtime/colors/default.vim
index fac120ccf5..8ee18a4ec4 100644
--- a/runtime/colors/default.vim
+++ b/runtime/colors/default.vim
@@ -2,12 +2,7 @@
 " Maintainer:	The Neovim Project <https://github.com/neovim/neovim>
 " Last Change:	2023 Dec 01
 
-" This is the default color scheme.
-
-" Set 'background' back to the default. The value can't always be estimated
-" and is then guessed.
-hi clear Normal
-set bg&
+" This is the default color scheme. See `:help dev_theme`.
 
 " Remove all existing highlighting and set the defaults.
 hi clear
diff --git a/runtime/colors/vim.vim b/runtime/colors/vim.vim
index 3418abe424..0d02477ba7 100644
--- a/runtime/colors/vim.vim
+++ b/runtime/colors/vim.vim
@@ -14,8 +14,8 @@ let g:colors_name = 'vim'
 
 " General
 hi Conceal      guifg=LightGrey guibg=DarkGrey guisp=NONE gui=NONE         ctermfg=LightGrey ctermbg=DarkGrey cterm=NONE
-hi Cursor       guifg=bg        guibg=fg       guisp=NONE gui=NONE         ctermfg=bg        ctermbg=fg       cterm=NONE
-hi lCursor      guifg=bg        guibg=fg       guisp=NONE gui=NONE         ctermfg=bg        ctermbg=fg       cterm=NONE
+hi Cursor       guifg=bg        guibg=fg       guisp=NONE gui=NONE         ctermfg=NONE      ctermbg=NONE     cterm=NONE
+hi lCursor      guifg=bg        guibg=fg       guisp=NONE gui=NONE         ctermfg=NONE      ctermbg=NONE     cterm=NONE
 hi DiffText     guifg=NONE      guibg=Red      guisp=NONE gui=bold         ctermfg=NONE      ctermbg=Red      cterm=bold
 hi ErrorMsg     guifg=White     guibg=Red      guisp=NONE gui=NONE         ctermfg=White     ctermbg=DarkRed  cterm=NONE
 hi IncSearch    guifg=NONE      guibg=NONE     guisp=NONE gui=reverse      ctermfg=NONE      ctermbg=NONE     cterm=reverse
@@ -214,7 +214,7 @@ if &background ==# 'light'
   hi SpellRare    guifg=NONE      guibg=NONE         guisp=Magenta  gui=undercurl ctermfg=NONE        ctermbg=LightMagenta cterm=NONE
   hi TabLine      guifg=NONE      guibg=LightGrey    guisp=NONE     gui=underline ctermfg=black       ctermbg=LightGrey    cterm=underline
   hi Title        guifg=Magenta   guibg=NONE         guisp=NONE     gui=bold      ctermfg=DarkMagenta ctermbg=NONE         cterm=NONE
-  hi Visual       guifg=NONE      guibg=LightGrey    guisp=NONE     gui=NONE      ctermfg=NONE        ctermbg=NONE         cterm=NONE
+  hi Visual       guifg=NONE      guibg=LightGrey    guisp=NONE     gui=NONE      ctermfg=NONE        ctermbg=LightGrey    cterm=NONE
   hi WarningMsg   guifg=Red       guibg=NONE         guisp=NONE     gui=NONE      ctermfg=DarkRed     ctermbg=NONE         cterm=NONE
   hi Comment      guifg=Blue      guibg=NONE         guisp=NONE     gui=NONE      ctermfg=DarkBlue    ctermbg=NONE         cterm=NONE      term=bold
   hi Constant     guifg=Magenta   guibg=NONE         guisp=NONE     gui=NONE      ctermfg=DarkRed     ctermbg=NONE         cterm=NONE      term=underline
@@ -253,7 +253,7 @@ else
   hi SpellRare    guifg=NONE     guibg=NONE        guisp=Magenta gui=undercurl ctermfg=NONE         ctermbg=Magenta     cterm=NONE
   hi TabLine      guifg=NONE     guibg=DarkGrey    guisp=NONE    gui=underline ctermfg=white        ctermbg=DarkGrey    cterm=underline
   hi Title        guifg=Magenta  guibg=NONE        guisp=NONE    gui=bold      ctermfg=LightMagenta ctermbg=NONE        cterm=NONE
-  hi Visual       guifg=NONE     guibg=DarkGrey    guisp=NONE    gui=NONE      ctermfg=NONE         ctermbg=NONE        cterm=NONE
+  hi Visual       guifg=NONE     guibg=DarkGrey    guisp=NONE    gui=NONE      ctermfg=NONE         ctermbg=DarkGrey    cterm=NONE
   hi WarningMsg   guifg=Red      guibg=NONE        guisp=NONE    gui=NONE      ctermfg=LightRed     ctermbg=NONE        cterm=NONE
   hi Comment      guifg=#80a0ff  guibg=NONE        guisp=NONE    gui=NONE      ctermfg=Cyan         ctermbg=NONE        cterm=NONE      term=bold
   hi Constant     guifg=#ffa0a0  guibg=NONE        guisp=NONE    gui=NONE      ctermfg=Magenta      ctermbg=NONE        cterm=NONE      term=underline
diff --git a/runtime/doc/dev_theme.txt b/runtime/doc/dev_theme.txt
index 04ec3f293c..29a2da0d90 100644
--- a/runtime/doc/dev_theme.txt
+++ b/runtime/doc/dev_theme.txt
@@ -18,8 +18,8 @@ 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 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).
@@ -49,8 +49,7 @@ Palettes
 - 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.
+    - 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),
@@ -67,8 +66,17 @@ Palettes
   (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.
+- 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.
 
 
 ==============================================================================
@@ -91,13 +99,23 @@ Use:
 - 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|.
+- Yellow very sparingly 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`).
+- 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:
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 406ac879eb..925c63f259 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -92,9 +92,22 @@ 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.
+• Default color scheme has been updated to be "Nvim branded" and accessible.
   Use `:colorscheme vim` to revert to the old legacy color scheme.
 
+  Here is a list of Nvim specific highlight groups which are now defined in
+  a meaningfully different way and might need an update:
+  • |hl-FloatBorder| is linked to |hl-NormalFloat| instead of |hl-WinSeparator|.
+  • |hl-NormalFloat| is not linked to |hl-Pmenu|.
+  • |hl-WinBar| is linked to |hl-StatusLine|.
+  • |hl-WinBarNC| is linked to |hl-StatusLineNC| instead of |hl-WinBar|.
+  • |hl-WinSeparator| is linked to |hl-Normal| instead of |hl-VertSplit|.
+
+  This also might result into some color schemes looking differently due to
+  them relying on an implicit assumptions about how highlight groups are
+  defined by default. To account for this, define all attributes of highlight
+  groups explicitly or use `:colorscheme vim` to restore previous definitions.
+
 • 'termguicolors' is enabled by default when Nvim is able to determine that
   the host terminal emulator supports 24-bit color.
 
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 1d02e49071..6b5f0393ea 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -5136,6 +5136,18 @@ guisp={color-name}					*guisp*
 	    Black	White
 	    Orange	Purple		Violet
 
+	Colors which define Nvim's default color scheme:
+	    NvimDarkBlue    NvimLightBlue
+	    NvimDarkCyan    NvimLightCyan
+	    NvimDarkGreen   NvimLightGreen
+	    NvimDarkGrey1   NvimLightGrey1
+	    NvimDarkGrey2   NvimLightGrey2
+	    NvimDarkGrey3   NvimLightGrey3
+	    NvimDarkGrey4   NvimLightGrey4
+	    NvimDarkMagenta NvimLightMagenta
+	    NvimDarkRed     NvimLightRed
+	    NvimDarkYellow  NvimLightYellow
+
 	You can also specify a color by its RGB (red, green, blue) values.
 	The format is "#rrggbb", where
 		"rr"	is the Red value
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 220505f573..e0ad0ff0f9 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -30,8 +30,10 @@ 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|.
+- Default color scheme has been updated. This can result in color schemes
+  looking differently due to them relying on how highlight groups are defined
+  by default. Add ":colorscheme vim" to |init.vim| or your color scheme file to
+  restore the old default links and colors.
 
 - 'autoindent' is enabled
 - 'autoread' is enabled (works in all UIs, including terminal)