Skip to main content
Version: 0.0.8

Extending Themes

histuid supports partial themes that inherit from existing themes. This allows you to create minimal customizations without duplicating entire theme files.

How Inheritance Works​

When you create a theme, histuid automatically provides defaults from the embedded default theme:

ComponentBehavior
CSSUse @import to include base theme styles
LayoutFalls back to default's layout.xml if none provided
ManifestMerged with default's manifest (sounds, icons)

Creating a Color-Only Theme​

The simplest partial theme overrides just the color palette:

/* ~/.config/histui/themes/my-colors.css */
@import "default.css";

/* Override just the colors */
.notification-popup {
    background-color: #2d2d44;
    color: #e0e0e0;
    border-color: #4a4a6a;
}

.notification-popup.urgency-critical {
    background-color: #442d2d;
    border-color: #ff6b6b;
}

This theme:

  • Imports all default styles
  • Overrides specific colors
  • Inherits the default layout and sounds automatically

Import Resolution​

Imports are resolved in this order:

  1. Relative to current file - ./colors.css
  2. User themes directory - mytheme/theme.css → ~/.config/histui/themes/mytheme/theme.css
  3. Embedded themes - default.css → embedded default theme

Import Formats​

/* Import embedded themes */
@import "default.css";           /* Embedded 'default' theme */
@import "minimal.css";           /* Embedded 'minimal' theme */
@import "default/theme.css";     /* Same as "default.css" */

/* Import user themes */
@import "mytheme/theme.css";     /* User theme 'mytheme' */
@import "mytheme/colors.css";    /* Any CSS file in mytheme/ */

/* Import shared files from themes root */
@import "colors.css";            /* ~/.config/histui/themes/colors.css */
@import "_variables.css";        /* Shared partials (underscore convention) */

/* Import relative files */
@import "./partials/buttons.css";

Shared Partials​

You can place shared CSS files directly in the themes directory for reuse across multiple themes:

~/.config/histui/themes/
├── _colors.css          # Shared color palette
├── _fonts.css           # Shared font settings
├── theme-a/
│   └── theme.css        # @import "_colors.css";
└── theme-b/
    └── theme.css        # @import "_colors.css";

_colors.css:

/* GTK CSS uses * instead of :root for global variables */
* {
    --my-bg: #1e1e2e;
    --my-fg: #cdd6f4;
    --my-accent: #89b4fa;
    --my-border: #45475a;
}

theme-a/theme.css:

@import "default.css";
@import "_colors.css";  /* Shared colors */

.notification-popup {
    background-color: var(--my-bg);
    color: var(--my-fg);
    border-color: var(--my-border);
}
Naming convention

Use an underscore prefix (_colors.css) for import-only files. These won't appear as selectable themes since they're not in a theme directory.

Dynamic Color Generation​

External tools can write color palettes directly to the themes directory. For example, tinct generates colors from images:

~/.config/histui/themes/
├── tinct-colors.css     # Generated by tinct from wallpaper
└── tinct/
    └── theme.css        # Your theme that uses tinct colors

tinct-colors.css (auto-generated):

* {
    --tinct-bg: #1a1b26;
    --tinct-fg: #c0caf5;
    --tinct-accent: #7aa2f7;
    --tinct-red: #f7768e;
    --tinct-green: #9ece6a;
}

tinct/theme.css:

@import "default.css";
@import "tinct-colors.css";  /* Generated colors */

.notification-popup {
    background-color: var(--tinct-bg);
    color: var(--tinct-fg);
}

.notification-popup.urgency-critical {
    border-color: var(--tinct-red);
}

When tinct regenerates colors (e.g., on wallpaper change), histuid's hot-reload automatically picks up the new palette.

Directory-Based Partial Themes​

For themes with custom sounds but inherited styles:

~/.config/histui/themes/my-sounds/
├── theme.css           # Imports default, adds customizations
├── manifest.toml       # Only overrides sounds (inherits rest)
└── sounds/
    └── custom-alert.ogg

theme.css:

@import "default.css";

/* Add a subtle border effect */
.notification-popup {
    border-width: 2px;
}

manifest.toml:

# Only specify what you want to override
# Other urgency levels inherit from default

[audio.critical]
path = "sounds/custom-alert.ogg"
volume = 1.0

Manifest Merging​

User manifests are merged with the default manifest field-by-field:

FieldBehavior
name, description, author, versionUser value if set, otherwise default
icon.sizeUser value if non-zero, otherwise default (48)
audio.low, audio.normal, audio.criticalPer-urgency: user path/volume if set, otherwise default

Example: Override Only Critical Sound​

# ~/.config/histui/themes/alert-only/manifest.toml

[audio.critical]
path = "sounds/alarm.ogg"
volume = 1.0
repeat_count = 3
repeat_delay = "5s"

# audio.normal and audio.low are inherited from default

Extending User Themes​

You can extend other user themes, not just embedded ones:

/* ~/.config/histui/themes/my-variant/theme.css */
@import "base-theme/theme.css";   /* Imports ~/.config/histui/themes/base-theme/theme.css */
@import "base-theme/colors.css";  /* Any CSS file from that theme */

/* Add your customizations */
.notification-popup {
    border-radius: 0;  /* Square corners */
}

Practical Examples​

Dark Mode Override​

/* ~/.config/histui/themes/dark.css */
@import "default.css";

* {
    --histui-font-size: 15px;
}

.notification-popup {
    background-color: rgba(30, 30, 46, 0.95);
    color: #cdd6f4;
    border-color: #45475a;
}

.notification-summary {
    color: #f5e0dc;
}

Compact Variant​

/* ~/.config/histui/themes/compact-custom.css */
@import "compact.css";  /* Start from embedded compact theme */

.notification-popup {
    padding: 6px;
    margin: 4px;
}

.notification-icon {
    min-width: 24px;
    min-height: 24px;
}

Corporate Branding​

~/.config/histui/themes/corporate/
├── theme.css
├── manifest.toml
└── sounds/
    └── chime.ogg

theme.css:

@import "default.css";

.notification-popup {
    background-color: #1a365d;
    border-color: #2b6cb0;
}

.notification-popup.urgency-critical {
    background-color: #742a2a;
    border-color: #c53030;
}

manifest.toml:

name = "Corporate"
description = "Company branding theme"
version = "1.0.0"

[audio.normal]
path = "sounds/chime.ogg"
volume = 0.7

# Critical sound inherited from default

Tips​

  1. Start minimal - Import a base theme and override only what you need
  2. Use CSS variables - Override * selector variables for consistent changes (GTK CSS uses * not :root)
  3. Test incrementally - Hot-reload updates your theme as you save
  4. Check the CSS reference - See CSS Reference for all available classes

See Also​