clrs

Minimal theme workflow for local tools.

clrs manages a current theme state in ~/.config/clrs/using.json, exports a normalized base24 palette, and refreshes tmux theme variables when switching themes.

Setup

Initialize dependencies and generate themes:

clrs setup

This will install jq and yq if needed, clone tinted-theming/schemes, convert base16 themes into normalized JSON files, and create a default using.json.

Palette Model

Input themes come from upstream base16 schemes. clrs normalizes neutral ramps and derives 8 additional base24 colors:

• Trusted input: name, base00, base05, base08..base0F
• Normalized: base01..base04, base06..base07 (rebuilt for consistent contrast)
• Derived: base10..base17 (extended palette for UI accents)

Base24 Semantic Reference

Base16/24	Semantic	Usage
base00	bg	Core background
base01	bg_sub	Secondary background (statusline/sidebar)
base02	bg_line	Line/block background (selection)
base03	fg_ghost	Dimmest text (comments)
base04	fg_low	Dim text (linenumbers/dividers)
base05	fg	Primary text (standard code)
base06	fg_high	Bright text (selected item/title)
base07	fg_max	Brightest text (search highlight)
base08	red	Variables/errors
base09	orange	Numbers/constants
base0A	yellow	Types/warnings
base0B	green	Strings/Git additions
base0C	cyan	Operators/regex
base0D	blue	Functions/properties
base0E	purple	Keywords
base0F	brown	Special markers
base10	bg_dark	Darker background (popup menu)
base11	red_bright	Bright red (error blocks)
base12	orange_bright	Bright orange
base13	yellow_bright	Bright yellow (warnings)
base14	green_bright	Bright green (success)
base15	cyan_bright	Bright cyan (info)
base16	blue_bright	Bright blue (Git/folds)
base17	purple_bright	Bright purple (emphasis)

Common Commands

clrs list              # List available themes
clrs use <theme>       # Switch to theme (updates using.json and tmux)
clrs current           # Show current theme name
clrs show              # Show theme summary
clrs show palette      # Show flat palette values
clrs show tmux         # Show tmux variables

Export Formats

clrs export json       # Flat JSON: { name, base00..base17 }
clrs export lua        # Lua table (for Neovim)
clrs export shell      # Shell variables: NAME, BASE00..BASE17
clrs export tmux       # Tmux theme variables

# Example: source colors in shell
eval "$(clrs export shell)"

Tmux Integration

clrs use <theme> automatically exports all 24 base24 colors to ~/.config/tmux/clrs.conf with semantic comments.

Setup - Add to ~/.config/tmux/tmux.conf:

source-file ~/.config/tmux/clrs.conf

Usage - Reference base16/24 variables with semantic comments:

# Export includes comments like:
# set -g @base00 "#282c34"              # bg - Core background
# set -g @base05 "#abb2bf"              # fg - Primary text
# set -g @base0D "#61afef"              # blue - Functions/properties

set -g status-style "fg=#{@base05},bg=#{@base01}"
set -g pane-active-border-style "fg=#{@base0D}"
set -g window-status-current-style "fg=#{@base06},bg=#{@base10},bold"

Run clrs show tmux to see all available variables with their semantic meanings.

Neovim Integration

Load the current theme palette in Neovim:

local theme = load(vim.fn.system("clrs export lua"))()

-- Theme contains: name, base00..base17
vim.api.nvim_set_hl(0, "Normal", { fg = theme.base05, bg = theme.base00 })
vim.api.nvim_set_hl(0, "Comment", { fg = theme.base03, italic = true })
vim.api.nvim_set_hl(0, "Function", { fg = theme.base0D })
vim.api.nvim_set_hl(0, "Keyword", { fg = theme.base0E })

The exported Lua table is flat: { name = "...", base00 = "#...", ..., base17 = "#..." }

Project Layout

clrs                   # Main CLI entry
scripts/
  bootstrap/           # Setup scripts
  theme/               # Export and build pipeline
  color-tools/         # Color manipulation library
assets/                # Cloned upstream themes (gitignored)
dist/                  # Generated JSON themes (gitignored)
using.json             # Current theme state (gitignored)

Only the workflow itself is tracked in git. Runtime/generated content is ignored.