Themes

Theme System

Themes are pure variable exports. Each theme file sets the same 15 @theme-* user options. Modules reference these variables (#{@theme-accent}) instead of hardcoding hex values. Switching themes requires changing one line in tmux.conf.

Available Themes

Theme Palette Character

aethelred.conf

Purple gradient (#8b5cf6 accent)

Deep, elegant — the default

solar-flare.conf

Warm orange (#f97316 accent)

High energy, high contrast

tokyo-night.conf

Cool blue (#7aa2f7 accent)

Clean, calm, nocturnal

Variable Contract

Every theme MUST export all 15 variables. Modules depend on this contract — a missing variable breaks rendering.

Variable Purpose Example (aethelred)

@theme-bg

Base background

#1a1b26

@theme-fg

Base foreground

#c0caf5

@theme-accent

Primary accent

#8b5cf6

@theme-accent-bright

Bright accent variant

#a78bfa

@theme-accent-dark

Dark accent variant

#6d28d9

@theme-green

Success, clean state

#9ece6a

@theme-yellow

Warning, attention

#fbbf24

@theme-red

Error, danger, OFF state

#f7768e

@theme-cyan

Info, secondary highlight

#7dcfff

@theme-blue

Tertiary accent

#7aa2f7

@theme-muted

Subdued text

#565f89

@theme-surface

Elevated surface

#24283b

@theme-surface-bright

Brighter surface

#414868

@theme-copy-bg

Copy mode highlight bg

#8b5cf6

@theme-copy-fg

Copy mode highlight fg

#1a1b26

How Themes Propagate

Theme is sourced BEFORE modules that reference variables:

core → vim → mouse → [THEME] → clipboard → panes → sessions → ...

References in modules:

  • lib/status.conf — status bar colors, window format

  • lib/panes.conf — pane border format with @theme-accent, @theme-muted

  • lib/sessions.conf — nested tmux OFF state uses @theme-surface, @theme-red

  • lib/modern.conf — popup border color

  • plugins/tpm.conf — prefix-highlight colors

Switching Themes

Manual (edit tmux.conf)

Change line 15 of tmux.conf:

source-file ~/.config/tmux/themes/tokyo-night.conf

Then reload: C-a r

Interactive (theme-switcher.sh)

~/.config/tmux/scripts/theme-switcher.sh --fzf     # interactive with preview
~/.config/tmux/scripts/theme-switcher.sh --next     # cycle to next
~/.config/tmux/scripts/theme-switcher.sh tokyo-night # switch by name

The script modifies tmux.conf (with backup), then reloads automatically if inside tmux.

Adding a New Theme

  1. Copy an existing theme as template: cp themes/aethelred.conf themes/my-theme.conf

  2. Change all 15 color values

  3. Keep the variable names identical — the contract must hold

  4. Test: source manually, verify status bar, pane borders, copy mode highlight, nested OFF state