Customization

Customize your Zirconium system with dotfiles, theming, and appearance settings

Overview

Zirconium provides extensive customization options while maintaining a consistent and polished experience. The system uses chezmoi to manage dotfiles, matugen for color scheme generation, and various tools for theming and appearance.

Dotfiles with zdots

Zirconium uses zdots - a curated collection of dotfiles managed by chezmoi.

How zdots works

1. System installation

   zdots are cloned to /usr/share/zirconium/zdots during the image build:

   git clone "https://github.com/zirconium-dev/zdots.git" /usr/share/zirconium/zdots
   
2. First login

   On your first graphical login, chezmoi-init.service applies the default configuration:

   chezmoi apply -S /usr/share/zirconium/zdots \
     --config ~/.config/zirconium/chezmoi/chezmoi.toml
   
3. Automatic updates

   The chezmoi-update.timer periodically syncs your dotfiles with zdots, prompting to skip conflicts.

What zdots manages

zdots provides configuration for:

• Niri: Window manager configuration (~/.config/niri/)
• DankMaterialShell: UI shell and panels (~/.config/DankMaterialShell/)
• Shell: bash, fish, and other shell configurations
• Terminal: foot terminal emulator settings
• Color schemes: Generated by matugen
• Application settings: Various application defaults

Chezmoi configuration

User config location: ~/.config/zirconium/chezmoi/chezmoi.toml

System source: /usr/share/zirconium/zdots

View zdots justfile path

The justfile defines zdots path as:

zdots_path := "/usr/share/zirconium/zdots"

OS update behavior with dotfiles

Understanding how Zirconium handles dotfiles during updates is crucial for maintaining your customizations.

Automatic update behavior

By default, Zirconium automatically updates your dotfiles:

1. On OS update

   When you update Zirconium (rpm-ostree upgrade or bootc upgrade), the zdots in /usr/share/zirconium/zdots are updated to the latest version.

2. On next login

   The chezmoi-update.timer runs and attempts to apply the new zdots configuration.

3. Conflict handling

   If you’ve modified configuration files, chezmoi will prompt:

   yes s | chezmoi apply --no-tty --keep-going -S /usr/share/zirconium/zdots --verbose
   

   The yes s automatically skips conflicts, preserving your changes.

While yes s skips conflicting files, you may miss important upstream improvements. Review changes periodically.

Managing dotfile updates

You have several options for controlling dotfile updates:

1. Accept all updates (default)

Let zdots manage everything automatically:

# This is the default behavior
systemctl --user is-enabled chezmoi-update.timer

2. Disable automatic updates

Maintain full control over your dotfiles:

# Disable automatic dotfile updates
zjust toggle-automatic-dotfiles

# Or manually
systemctl --user disable --now chezmoi-update.timer
systemctl --user mask chezmoi-update.timer
systemctl --user disable chezmoi-init.service
systemctl --user mask chezmoi-init.service

When disabled, your dotfiles remain frozen at their current state. You can manually update when ready.

3. Manual selective updates

Update dotfiles on your own schedule:

# Update all dotfiles (with conflict prompts)
zjust zdots-update

# Reset specific file to zdots default
zjust zdots-reset ~/.config/niri/config.kdl

# Reset everything (requires confirmation)
zjust zdots-override-all

Chezmoi systemd services

chezmoi-init.service

# /usr/lib/systemd/user/chezmoi-init.service
[Unit]
Description=Initializes Chezmoi if directory is missing
ConditionPathExists=!%h/.config/zirconium/chezmoi

[Service]
ExecStart=mkdir -p %h/.config/zirconium/chezmoi
ExecStart=touch %h/.config/zirconium/chezmoi/chezmoi.toml
ExecStart=chezmoi apply -S /usr/share/zirconium/zdots --config %h/.config/zirconium/chezmoi/chezmoi.toml
Type=oneshot

[Install]
WantedBy=graphical-session-pre.target

Theming and appearance

Zirconium provides comprehensive theming through multiple coordinated systems.

Color scheme generation with matugen

matugen generates Material Design 3 color schemes from wallpapers or colors.

Installed from: zirconium/packages COPR repository

matugen creates:

• DMS color schemes (~/.cache/DankMaterialShell/dms-colors.json)
• GTK/Qt theme colors
• Terminal color schemes
• Coordinated system-wide palette

Setting accent colors

Change your system accent color:

# Interactive color picker
zjust set-accent-color
# Options: blue, teal, green, yellow, orange, red, pink, purple, slate

# Or set directly
gsettings set org.gnome.desktop.interface accent-color "teal"

Accent color changes automatically update DMS theme and panel colors.

Qt theming

Zirconium uses qt6ct for Qt application theming:

# /etc/profile.d/zirconium-qt-override.sh
export QT_QPA_PLATFORMTHEME=qt6ct

Installed Qt components:

• qt6ct - Qt6 Configuration Tool
• plasma-breeze - Breeze theme for Qt
• kf6-qqc2-desktop-style - QtQuickControls2 desktop style
• kf6-kirigami - Kirigami UI framework

Fonts

Zirconium includes carefully selected fonts:

• Maple fonts: Installed from Terra repository
• Noto Emoji: Google Noto Color Emoji fonts
• System fonts: default-fonts and default-fonts-core-emoji

Font rendering

Optimized font rendering settings:

# /etc/profile.d/zirconium-font-settings.sh
export FREETYPE_PROPERTIES="cff:no-stem-darkening=0 autofitter:no-stem-darkening=0"

Font cache is regenerated during build:

fc-cache --force --really-force --system-only --verbose

Wallpapers

Default wallpapers are provided in:

/usr/share/zirconium/skel/Pictures/Wallpapers/

These are installed during the image build from /ctx/assets/wallpapers/.

Additional customization tools

Zirconium includes several tools for advanced customization:

chezmoi

Powerful dotfile manager with templating support.

# View managed files
chezmoi managed

# Check for differences
chezmoi diff

# Apply specific source
chezmoi apply -S /usr/share/zirconium/zdots

# Edit a file with chezmoi
chezmoi edit ~/.config/niri/config.kdl

Using chezmoi templates

You can use chezmoi’s templating to create conditional configurations:

# In your zdots fork, use templates like:
{{ if eq .hostname "laptop" }}
# Laptop-specific config
{{ else }}
# Desktop config
{{ end }}

fastfetch and hyfetch

System information display tools:

# Display system info
fastfetch

# Display with pride flags
hyfetch

Configuration: /usr/share/zirconium/fastfetch.jsonc

just (zjust)

Task runner for common Zirconium operations:

# Interactive menu
zjust
# Equivalent to: zjust --choose

# List all available recipes
zjust --list

Justfile location: /usr/share/zirconium/just/00-start.just

Includes Universal Blue recipes:

import "/usr/share/ublue-os/just/update.just"
import "/usr/share/ublue-os/just/shared.just"
import "/usr/share/ublue-os/just/default.just"

MOTD (Message of the Day)

Custom MOTD is displayed on login:

# Toggle MOTD display
zjust toggle-user-motd

# Manual display
zmotd

Scripts:

• /usr/bin/zmotd - MOTD generator
• /usr/bin/zfetch - System info for MOTD
• /usr/bin/glorpfetch - Alternative fetch tool

Advanced customization

Forking zdots

For deep customization, fork the zdots repository:

1. Fork zdots

   Fork zirconium-dev/zdots on GitHub.

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/zdots ~/my-zdots
   
3. Point chezmoi to your fork

   chezmoi init --apply --source ~/my-zdots
   
4. Disable automatic updates

   zjust toggle-automatic-dotfiles
   
5. Make changes

   Edit files in ~/my-zdots and apply:

   chezmoi apply
   

Creating a custom image

For the ultimate customization, build your own Zirconium variant:

1. Fork the zirconium repository
2. Modify build scripts in build_files/
3. Customize system files in system_files/
4. Build and host your custom image
5. Rebase to your custom image:
   sudo bootc switch ghcr.io/YOUR_USERNAME/zirconium:latest
   

Customization reference

Key files and directories

Path	Purpose
/usr/share/zirconium/zdots/	System zdots source
~/.config/zirconium/chezmoi/	User chezmoi config
~/.config/niri/	Niri window manager config
~/.config/DankMaterialShell/	DMS shell config
/usr/share/zirconium/just/	Justfile recipes
/etc/profile.d/	System environment variables

Common customization tasks

Change shell appearance

Edit shell configuration in zdots:

• bash: ~/.bashrc (sources /usr/share/zirconium/shell/pure.bash)
• fish: ~/.config/fish/config.fish

Or disable zdots updates and edit directly.

Customize panel

Edit DMS settings:

$EDITOR ~/.config/DankMaterialShell/settings.json
systemctl restart --user dms.service

Add custom keybindings

Edit Niri config:

$EDITOR ~/.config/niri/config.kdl
niri msg action reload-config

Install additional fonts

# User fonts
mkdir -p ~/.local/share/fonts
cp your-font.ttf ~/.local/share/fonts/
fc-cache -f -v

Next steps

Niri configuration

Deep dive into Niri window manager

DMS configuration

Customize DankMaterialShell components