xeno.nvim

Overview

xeno.nvim is a minimalist colorscheme generator for Neovim that creates complete themes from color seeds rather than requiring hand-crafted palettes. It generates complete Neovim colorschemes from three seeds — background, accent, and an optional foreground. The foreground defaults to the background seed's hue and chroma, so a single background + accent pair is enough to produce a coherent theme across every highlight group. The plugin provides automatic light/dark mode support, generating cohesive color palettes and highlight groups from just color inputs.

Core Capabilities

Color Generation

xeno derives a full 50–950 color scale from each seed using OKLCH color space, the perceptually linear color model that ensures predictable color scaling and contrast. It automatically generates shade families with semantic numbering (foreground: 50-400, background: 500-950, accent: 50-600) and supports variation control, chroma adjustment, and custom color families.

How it works

Pass your seeds to require('xeno').theme() and set the colorscheme:

require('xeno').theme('my-theme', {
  background = '#1E1E1E',
  accent = '#8CBE8C',
})
vim.cmd('colorscheme my-theme')

The plugin maps colors across syntax, UI, diagnostics, and plugin highlight groups automatically. It also supports advanced color control with variation parameters, chroma adjustment, contrast modification, and custom color families.

Light/Dark Mode

xeno seamlessly adapts to vim.o.background changes without requiring separate theme definitions. A single theme configuration automatically generates appropriate lightness scales for both light and dark modes with contrast-aware foreground adjustment to ensure readability.

Plugin Support

Built-in theming for 26+ plugins including Telescope, nvim-tree, bufferline, nvim-cmp, FZF-Lua, Neo-tree, Dropbar, Which-key, Gitsigns, Neogit, Diffview, Todo Comments, Trouble, Indent-blankline, Render-markdown, Markview, Navic, Glance, Grug-far, Avante, and Toggleterm. Each plugin exposes high-level options so you can tune things like selected_bg or border without touching individual highlight groups:

highlights = {
  plugins = {
    ["nvim-telescope/telescope.nvim"] = {
      bg = "@background.950",
      border = "@accent.500",
    },
  },
}

Use color references with @accent.500, @background.800, @foreground.100 notation, with fallback to shade .500 when omitted.

Theme Management

Create and manage multiple distinct themes simultaneously. Generate standalone colorscheme files for distribution and reuse. Use the namespace system to create per-window theme variants. Export current theme as a standalone Lua colorscheme file.

Terminal Integration

xeno provides automatic terminal color palette generation and direct Ghostty terminal color configuration. Terminal colors automatically sync with theme palette.

Use Cases

Primary Users:

• Neovim enthusiasts who want cohesive, custom colorschemes without manual palette creation
• Users who frequently switch between light and dark modes and need automatic theme adaptation
• Plugin-heavy Neovim configurations requiring consistent theme colors across multiple plugins
• Developers who want to create and distribute reusable colorscheme variations
• Teams needing consistent editor theming with customizable color bases

Typical Workflows:

1. Quick setup: specify background and accent colors, get complete theme immediately
2. Incremental customization: start with defaults, add custom colors and plugin tweaks as needed
3. Theme distribution: generate standalone colorscheme files for sharing with others
4. Per-project theming: use namespaces for window-specific theme variants
5. Dynamic theming: adjust colors based on user preference changes

What I learned

Generating perceptually consistent color scales from arbitrary hex seeds required working in OKLCH rather than HSL. The trickiest part was deriving a foreground that felt natural — not just a lightened version of the background, but something with the same hue character that could shift properly between light and dark mode.

Stack

• Language: Lua (pure Lua implementation)
• Color space: OKLCH
• Neovim API: Direct Neovim integration with vim. API for highlighting and commands
• Requires: Modern Neovim with Lua support, vim.api.nvim_set_hl(), autocommand support, and namespace support
• No external dependencies: Pure Lua implementation
• Plugin Manager Support: lazy.nvim and mini.deps