Technical Guidelines [WIP]

Technical Guidelines

Mandatory requirements

In order to be considered for bundling with Vim, a color scheme…

Must be fully functional in GUI Vim and TUI Vim

By "fully functional", we mean that, personal taste aside, the color scheme shouldn't break any built-in feature or impair usability, both in GUI Vim and in TUI Vim.

If, say, Folded is legible in TUI Vim and not in GUI Vim, then the color scheme should be considered broken.

Must be functional in environments that support 256 or fewer colors

Vim being a TUI program at its heart, we feel that every color scheme distributed with it should at least support color terminals.

In an effort to preserve and support Vim's many usage patterns, we expect authors to provide explicit support for both 256c-ready and 16c-ready terminal emulators.

Must not depend on scarcely supported stylistic features

Simply put, there is no way for the author of a color scheme to exert full control over how their work will look and feel in all situations. There are too many ways things can fail at one layer or another so it is best to not take anything for granted or count on some part of the whole system to be there to provide a sensible fallback.

For example, "true colors" is now relatively widely supported but a) it is not supported everywhere Vim can run, and b) it is not supported in the same way everywhere it is supported. Therefore, only providing gui* colors and relying on :help 'termguigolors' is not recommended.

For another example, :help highlight-ctermul is poorly supported across the board so exclusively relying on it for something as important as Statement or some similar highlight group is not recommended either.

The features below are widely supported so they are considered reliable:

• #RRGGBB values for guifg, guibg, and guisp in a GUI context,
• values in the 16-255 range for ctermfg and ctermbg in a 256 colors context,
• underline and reverse in any context,
• bold and italic in a GUI context,
• more?

The features below can technically be expected to work in many contexts but no guarantee can be made about the end result so they are considered unreliable:

• values in the 0-15 range for ctermfg and ctermbg in any non-GUI context,
• bold in any non-GUI context,
• termguicolors,
• more?

Support for the features below is spotty at best so they are considered highly unreliable:

• strikethrough and undercurl in any context,
• any value for guisp in a "true colors" context,
• more?

Support for color names in a 8-16 colors context is a special case. On one hand, it works reliably across terminal emulators and it is more compatible than numerical values. On the other hand, the terminal emulator's palette is a moving target: different terminal emulators have a different default palette and it is user-customizable anyway. So there is no way to guarantee that darkblue will consistently correspond to a specific blue… or that it will be some kind of blue to begin with.

Must degrade gracefully

If you decide to use one of the unreliable or highly unreliable features listed above, make sure it doesn't affect the usability of the color scheme when it is not available.

For example, italic falls back to reverse in some environments due to poor feature detection on Vim's part. Therefore, italic is not considered to degrade gracefully.

Must handle every built-in highlight group

Every highlight group under :help highlight-groups is mandatory, with the exception of :help hl-Menu, :help hl-ScrollBar, and :help hl-ToolTip, which are considered optional.

Two additional highlight groups not included in the list above should also be included: :help hl-debugPC and :help hl-debugBreakpoint.

Both Colortemplate and colors/tools/check_colors.vim will notify you if a group is missing.

Must be valid

A valid color scheme is a color scheme that passes all tests in colors/tools/check_colors.vim.

Optional requirements

In order to be considered for bundling with Vim, a color scheme should satisfy the following requirements.

Should avoid depending solely on typographic attributes to provide meaning

Yes, this is redundant, but it is important nonetheless. Some attributes are better supported than others but, in general, they are not reliable enough.

If the only way you found to distinct Statement from Identifier was to set it in italic, then think again.

Should avoid depending on external tool or setup

We believe that using a color scheme should be as simple as :colorscheme foobar and that no other action should be required from the user. This means no dependency on a specific terminal emulator palette/option/feature and no install script.

Should avoid exposing options to the user

For the same reason as above, color schemes should not depend on user-defined options. That practice makes color schemes brittle and adds the burden of writing a documentation that users won't read anyway.

Should avoid requiring any effort from the user…

…beyond :colorscheme foobar.