Skip to content

theme.adoc

Latest commit

 

History

History
369 lines (267 loc) · 8.29 KB

theme.adoc

File metadata and controls

369 lines (267 loc) · 8.29 KB

THEME(1) Manual Page

NAME

theme - extensible theme orchestrator for shell environments

SYNOPSIS

theme [OPTIONS] [dark|light]

DESCRIPTION

theme detects the system appearance (dark or light mode) and orchestrates theme configuration across multiple tools via an extensible detector/provider/handler system.

The command performs three steps:

  1. Detection - Determines system appearance (dark/light) using user-provided detector functions

  2. Provider - Calls a user-registered provider function that maps appearance to theme variables (e.g., THEME_VARIANT, THEME_ACCENT)

  3. Handlers - Calls all registered handler functions that configure individual tools using the exported theme variables

Detectors, providers, and handlers are auto-discovered by function name prefix or loaded from configuration files.

OPTIONS

-d, --detect

Only detect and print the system appearance (dark or light). Does not run the provider or handlers.

-l, --list

List the discovered detectors, provider, and all registered handlers.

-q, --quiet

Suppress warning messages.

-h, --help

Show help message and exit.

-V, --version

Show version information and exit.

ARGUMENTS

dark | light

Override the detected appearance. When specified, detection is skipped and this value is passed directly to the provider.

DETECTORS

Detectors are user-provided shell functions that detect the system appearance. This allows users to implement detection for their specific system rather than relying on hardcoded methods.

Detector Contract

Detectors must:

  • Be named with prefix theme_detector_ (e.g., theme_detector_macos)

  • Return 1 if detection doesn’t apply (wrong OS, missing tools)

  • Return 0 and set THEME_APPEARANCE=dark or THEME_APPEARANCE=light on success

Detector Discovery

Detectors are discovered from:

  1. Functions matching theme_detector_* in current shell

  2. Functions defined in scripts under ~/.config/theme/detectors.d/*.sh

Detectors are tried in alphabetical order. The first one that returns 0 wins.

Detection Fallback

If no detector succeeds:

  1. Uses THEME environment variable if set to "dark" or "light"

  2. Otherwise defaults to "light"

Example Detectors

macOS
theme_detector_macos() {
  [[ "$(uname -s)" == "Darwin" ]] || return 1
  command -v defaults >/dev/null || return 1

  if defaults read -g AppleInterfaceStyle 2>/dev/null | grep -qi dark; then
    THEME_APPEARANCE=dark
  else
    THEME_APPEARANCE=light
  fi
}
GNOME
theme_detector_gnome() {
  [[ "${XDG_CURRENT_DESKTOP:-}" == *GNOME* ]] || return 1
  command -v gsettings >/dev/null || return 1

  local scheme
  scheme=$(gsettings get org.gnome.desktop.interface color-scheme 2>/dev/null) || return 1

  case "$scheme" in
    *dark*) THEME_APPEARANCE=dark ;;
    *)      THEME_APPEARANCE=light ;;
  esac
}
KDE Plasma
theme_detector_kde() {
  command -v kreadconfig5 >/dev/null || return 1

  local scheme
  scheme=$(kreadconfig5 --file kdeglobals --group General --key ColorScheme 2>/dev/null) || return 1

  case "${scheme,,}" in
    *dark*) THEME_APPEARANCE=dark ;;
    *)      THEME_APPEARANCE=light ;;
  esac
}
Windows (WSL)
theme_detector_wsl() {
  [[ -n "${WSL_DISTRO_NAME:-}" ]] || return 1
  command -v reg.exe >/dev/null || return 1

  local result
  result=$(reg.exe query "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize" /v AppsUseLightTheme 2>/dev/null) || return 1

  if [[ "$result" == *"0x0"* ]]; then
    THEME_APPEARANCE=dark
  else
    THEME_APPEARANCE=light
  fi
}

PROVIDERS

A provider is a shell function that receives the detected appearance and exports theme variables for handlers to consume.

Provider Contract

Providers must:

  • Be named with prefix theme_provider_ (e.g., theme_provider_catppuccin)

  • Accept two arguments: $1 = appearance (dark|light), $2 = source (detected|default|override)

  • Export THEME and any additional variables handlers need

Provider Discovery

Providers are discovered in order:

  1. Functions matching theme_provider_* in current shell

  2. Functions defined in ~/.config/theme/provider.sh

Only the first discovered provider is used.

Example Provider

theme_provider_catppuccin() {
  local appearance="$1"  # dark | light
  local source="$2"      # detected | default | override

  export THEME="$appearance"

  case "$appearance" in
    dark)  export THEME_VARIANT=mocha ;;
    light) export THEME_VARIANT=latte ;;
  esac

  export THEME_ACCENT=blue
}

HANDLERS

Handlers are shell functions that configure individual tools using the theme variables exported by the provider.

Handler Contract

Handlers must:

  • Be named with prefix theme_handler_ (e.g., theme_handler_bat)

  • Read configuration from THEME_* environment variables

  • Configure their target tool (export vars, write config files, etc.)

Handler Discovery

Handlers are discovered from:

  1. Functions matching theme_handler_* in current shell

  2. Functions defined in scripts under ~/.config/theme/handlers.d/*.sh

All discovered handlers are executed in alphabetical order.

Example Handlers

theme_handler_bat() {
  export BAT_THEME="Catppuccin ${THEME_VARIANT^}"
}

theme_handler_vivid() {
  export LS_COLORS="$(vivid generate catppuccin-${THEME_VARIANT})"
}

theme_handler_fzf() {
  if [[ "$THEME" == "dark" ]]; then
    export FZF_DEFAULT_OPTS="--color=dark"
  else
    export FZF_DEFAULT_OPTS="--color=light"
  fi
}

External Handler Files

Handlers can be defined in separate files under ~/.config/theme/handlers.d/:

~/.config/theme/handlers.d/bottom.sh
#!/usr/bin/env bash
theme_handler_bottom() {
  export BTM_CONFIG_FILE="$HOME/.config/bottom/themes/${THEME_VARIANT}.toml"
}

FILES

~/.config/theme/config.sh

User configuration file. Sourced after detectors but before provider/handler discovery. Can be used to set default variables or configure behavior.

~/.config/theme/detectors.d/.sh*

Detector scripts. All .sh files in this directory are sourced first. Define theme_detector_* functions to detect system appearance.

~/.config/theme/provider.sh

Custom provider definition. Sourced during provider discovery.

~/.config/theme/handlers.d/.sh*

External handler scripts. All .sh files in this directory are sourced during handler discovery.

ENVIRONMENT

THEME

Current theme appearance (dark or light). Set by the provider. Can also be set manually to override detection.

THEME_VARIANT

Theme variant name (e.g., mocha, latte). Set by the provider.

THEME_ACCENT

Accent color (e.g., blue, pink). Set by the provider.

Additional THEME_* variables may be exported by custom providers.

EXIT STATUS

0

Success.

1

Runtime error (no provider found, detection failed).

2

Usage error (invalid arguments).

EXAMPLES

Detect appearance and apply theme to all handlers
theme
Force dark mode
theme dark
Only detect appearance (no handlers)
theme --detect
List discovered provider and handlers
theme --list

Shell Integration

Add to shell configuration for automatic theming on startup:

# ~/.bashrc or ~/.zshrc
source /path/to/theme.sh

# Define detector (required - detection is user-provided)
theme_detector_macos() {
  [[ "$(uname -s)" == "Darwin" ]] || return 1
  if defaults read -g AppleInterfaceStyle 2>/dev/null | grep -qi dark; then
    THEME_APPEARANCE=dark
  else
    THEME_APPEARANCE=light
  fi
}

# Define provider
theme_provider_catppuccin() {
  local appearance="$1"
  export THEME="$appearance"
  case "$appearance" in
    dark)  export THEME_VARIANT=mocha ;;
    light) export THEME_VARIANT=latte ;;
  esac
  export THEME_ACCENT=blue
}

# Define handlers
theme_handler_bat() {
  export BAT_THEME="Catppuccin ${THEME_VARIANT^}"
}

theme_handler_vivid() {
  export LS_COLORS="$(vivid generate catppuccin-${THEME_VARIANT})"
}

# Apply theme on shell startup
theme

SEE ALSO

defaults(1), gsettings(1), vivid(1), bat(1)

AUTHORS

Scriptorium contributors.