Skip to content

Latest commit

 

History

History
62 lines (46 loc) · 3.13 KB

CONTRIBUTING.md

File metadata and controls

62 lines (46 loc) · 3.13 KB
Raw

Contributing

Setup

If you have Nix then you can just add enter the provided dev shell. If you don't then you need:

  • Make
  • Lua 5.3 and above
  • Neovim (and ideally Vim to make sure the theme works there too)

Getting Started

For the common case of changing a color or adding a missing highlight group, you'll be working with src/themes/nvim/theme.lua and src/themes/nvim/template.lua. theme.lua is where we define key/value pairs, where the keys are arbitrary and the values are typically highlight groups or links (think hi! link foo bar). Even though the keys are arbitrary, it's good practice to name them after the highlight group they represent.

Here's an excerpt from the file showing what this typically looks like. The key is Normal and the value is a highlight group. The name field is what is rendered into Vimscript for the hi command. If we changed name = "Normal" to name = "Foo", then the hi command would be hi Foo .... The rest of the values are the same as what you'd expect from a hi command (e.g. guifg, guibg, etc.).

The values for e.g., guifg should always come from t value here, which is the set of available, semantic colors. Here's the full list of values:

  • term_black
  • term_red
  • term_green
  • term_yellow
  • term_blue
  • term_magenta
  • term_cyan
  • term_white
  • term_bright_black
  • term_bright_red
  • term_bright_green
  • term_bright_yellow
  • term_bright_blue
  • term_bright_magenta
  • term_bright_cyan
  • term_bright_white
  • success.fg, success.bg, success.fg_normal
  • error.fg, error.bg, error.fg_normal
  • warning.fg, warning.bg, warning.fg_normal
  • info.fg, info.bg, info.fg_normal
  • accent.fg, accent.bg, accent.fg_normal
  • canvas.fg, canvas.bg, canvas.fg_faint, canvas.fg_muted, canvas.border
  • layer{1,2,3,4}.fg, layer{1,2,3,4}.bg, layer{1,2,3,4}.fg_faint, layer{1,2,3,4}.fg_muted, layer{1,2,3,4}.border

The status colors (success, error, ...) have two different foreground colors. fg should only ever be used in conjunction with the bg color from the same status color. Otherwise the contrast between fg and bg might not be high enough. fg_normal can be used with the normal editor background. Generally not all possible combinations will have sufficient contrast (e.g., fg_normal might not work well with layer4.bg) but it mostly works.

Canvas and the 4 layers are essentially fg and bg colors for UI elements, ranging from the most basic editor background to popups, sidebars, status bars, etc.

Normal = hlgroup {
	name = "Normal",
	guifg = t.canvas.fg,
	guibg = t.canvas.bg,
}

The key/value pairs from theme.lua are used for string interpolation in template.lua. If you change an existing color, you don't need to open template.lua. If you add a new color, you'll need to add a corresponding line in the template. The syntax is ${Normal} where Normal is the key from theme.lua (not the name field). The template files are written in the language of the application they're for (Vimscript, YAML, ...).

For more information, see ARCHITECTURE.md.

Guidelines

  • Prefer general over specific; choose @lsp.typemod.function.declaration over @lsp.typemod.function.declaration.lua