How does g:terminal_ansi_colors affect the :terminal colors?

Question

:term usually looks ugly in most colorschemes I've tried. At least on Windows, with light themes, these colors do not work and end up in an unreadable shade of yellow against my light background.

I recently re-enabled papercolor-theme/PaperColor, and I noticed it changed the terminal colors. They terminal actually became readable. I dug into the code and found it (most likely) originates from g:terminal_ansi_colors, which is defined in the theme. Most themes only do this for Neovim, which requires a different variant, but I digress.

The documentation (:help g:terminal_ansi_colors) states:

                                                        *g:terminal_ansi_colors*
In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new
terminal windows may be configured using the variable
`g:terminal_ansi_colors`, which should be a list of 16 color names or
hexadecimal color codes, similar to those accepted by |highlight-guifg|.  When
not using GUI colors, the terminal window always uses the 16 ANSI colors of
the underlying terminal.
The |term_setansicolors()| function can be used to change the colors, and
|term_getansicolors()| to get the currently used colors.

But say I wanted to make my own colorscheme (or just make a different colorscheme that doesn't add support for g:terminal_ansi_colors readable) - how do I use it? Or to be more specific: how do each of the 16 values map to a color on the terminal, provided there is a system?

Answer 1

The help for the function term_setansicolors provides some more details. The short story is these 16 colors form a conventional palette which terminal programs use when outputting text. You can set them to anything you want, but it's best to stick to the vague color descriptions below.

term_setansicolors({buf}, {colors})         *term_setansicolors()*
        Set the ANSI color palette used by terminal {buf}.
        {colors} must be a List of 16 valid color names or hexadecimal
        color codes, like those accepted by |highlight-guifg|.
        Also see |term_getansicolors()| and |g:terminal_ansi_colors|.

        The colors normally are:
            0    black
            1    dark red
            2    dark green
            3    brown
            4    dark blue
            5    dark magenta
            6    dark cyan
            7    light grey
            8    dark grey
            9    red
            10   green
            11   yellow
            12   blue
            13   magenta
            14   cyan
            15   white

        These colors are used in the GUI and in the terminal when
        'termguicolors' is set.  When not using GUI colors (GUI mode
        or 'termguicolors'), the terminal window always uses the 16
        ANSI colors of the underlying terminal.
        {only available when compiled with the |+terminal| feature and
        with GUI enabled and/or the |+termguicolors| feature}