Skip to content

themes.md

Latest commit

 

History

History
190 lines (146 loc) · 7.14 KB

themes.md

File metadata and controls

190 lines (146 loc) · 7.14 KB
Raw

Themes

The theme system separates visual appearance (colors, icons, layout) from module configuration, allowing you to switch looks without touching your module setup.

Architecture

Themes operate at the config loading layer, before any rendering or plugin execution occurs.

config.jsonc (theme: "berlin", modules: [...])
       |
       v
   Load default Config
       |
       v
   Load user config.jsonc
       |
       v
   Load theme/<name>.jsonc
       |
       v
   Merge: defaults <- config.jsonc <- theme
       |
       v
   Final Config (used by renderer)

Merge Order (last wins)

Each layer can override any visual field. Starting from v0.2.0, the theme has the highest priority:

Layer Source Contains
1. Core defaults Hardcoded in config.rs Default icons, colors, layout
2. User config config.jsonc modules, info_plugins, plus overrides for any visual field
3. Theme file themes/<name>.jsonc colors, layout, palette_style, logo_path, logo_color, logo_colors, header_icons, footer_text, show_colors

A field in the theme file always wins over the same field in config.jsonc or defaults.

Merge details

The merge uses deep_merge() which works key-by-key:

  • Objects: merged recursively — each key is resolved independently
  • Strings, numbers, booleans: overlay replaces base
  • Empty strings: an empty string does not override a non-empty string (prevents themes from accidentally clearing icons)
  • Empty objects {}: no-op — existing keys are preserved

Upgrade note (v0.1.x → v0.2.0): In v0.1.x, config.jsonc won over the theme. If you upgrade, your existing config may override the theme. Export your current look with xfetch theme export my-look, set "theme": "my-look", and remove visual fields from config.jsonc.

Theme File Format

A theme file is a JSONC document containing only visual fields. It should NOT contain modules or info_plugins.

{
    "layout": "section",
    "show_colors": true,
    "palette_style": "circles",
    "colors": {
        "os": "Magenta",
        "cpu": "Red",
        "memory": "Yellow",
        "disk": "Cyan",
        "shell": "Green",
        "wm": "Blue"
    }
}

Supported Fields

Field Type Description
layout string or null Layout style name
colors object Per-module color mapping
palette_style string or null Palette display: squares, circles, triangles, lines
show_colors boolean Enable or disable inline ANSI color swatches
logo_path string or null Path to a logo file
logo_color string or null Color for ASCII logos (name, hex, or RGB)
logo_colors array or null Per-row colors for ASCII logos (row i uses logo_colors[i % len])
header_icons array or null Pac-Man layout header icons
footer_text string or null Pac-Man layout footer text

Themes do not carry icons — icon choice is up to the user's font; the core fills in icons from the built-in defaults.

Theme Resolution

When xfetch loads a config with theme: "dracula", the resolver searches in order:

  1. Direct path — If the value is a file path (contains / or starts with ~), load it directly
  2. Themes directory — Look for <name>.jsonc in ~/.config/xfetch/themes/

If the theme is not found, the config loads as-is without the theme.

CLI Commands

# List installed themes
xfetch theme list

# Activate a theme (sets "theme" field in config.jsonc)
xfetch theme set nord

# Remove a theme file
xfetch theme remove nord

# Export current visual config as a theme file
xfetch theme export my-theme

Export Behavior

xfetch theme export <name> captures the current runtime visual state (after merge) and writes it to ~/.config/xfetch/themes/<name>.jsonc. This allows sharing your look without exposing your module list.

The exported file contains only:

  • layout
  • colors
  • palette_style
  • header_icons
  • footer_text
  • logo_path
  • show_colors

Backward Compatibility

The theme system is fully backward compatible:

  • Without theme field: Everything works exactly as before. The config file contains all visual fields directly.
  • Existing configs: Can be migrated by exporting: xfetch theme export current, then setting "theme": "current" and removing visual fields from the main config.
  • Plugin configs: Plugin references (info_plugins) remain exclusively in config.jsonc, never in theme files.

Directory Structure

~/.config/xfetch/
    config.jsonc            # Modules, plugins, and optional theme reference
    themes/
        dracula.jsonc       # Theme files: colors, layout
        nord.jsonc
        catppuccin-mocha.jsonc
        retro-pacman.jsonc
        berlin.jsonc
        tree-compact.jsonc

Built-in Themes

The official themes repository is located at github.com/xfetch-cli/themes, registered via index.json with theme files under colors/:

Theme Layout Style
dracula section Dark magenta, red, and cyan palette
nord section Cool blue and arctic cyan palette
catppuccin-mocha section Warm mocha pastel palette
retro-pacman pacman Classic Pac-Man arcade style with header icons and footer text
berlin default No colors and no icons: clean text-only output
tree-compact tree Hierarchical tree layout with a cool blue-green scheme
bogota bottom Bottom layout with a warm red, magenta and white palette
helsinki line Single-line layout with a green, blue and magenta accent mix
lahabana section Section layout with a red, magenta and white palette
london minimal Minimal greyscale palette (white and grey)
madrid default Default layout with a red, green and blue tricolor palette
miami section Section layout with a magenta, cyan and white vaporwave palette
oslo compact Compact layout with a cool blue, cyan and white palette
paris box Box layout with a red, magenta and white palette
praha section Section layout with a red and magenta palette, triangle swatches
tokio horizontal Horizontal layout with a red, white and magenta palette
x section Section layout with a cyan, magenta and white accent set

Implementation Details

Config Loading (config.rs)

The merge uses serde_json::Value deep-merge before deserialization:

  1. Parse config.jsonc as serde_json::Value
  2. Deserialize to Config to extract the theme field
  3. If theme is set, load the theme file as serde_json::Value
  4. Create an empty Value and merge in order: defaults → config.jsonc → theme
  5. Deserialize the merged result to Config

Theme Management (themes/mod.rs)

  • list_themes() — Scans ~/.config/xfetch/themes/ for *.jsonc files
  • set_active_theme() — Reads config.jsonc, sets the theme field, writes back
  • remove_theme() — Deletes a theme file from the themes directory
  • export_current_theme() — Builds a JSONC file from the current Config's visual fields