Configuration
Theming and Customization
How wallpapers become colors, how light and dark mode work, and where to customize the shell safely.
ArchEclipse's theme is generated from the current wallpaper. There is no hand-maintained color scheme to edit: ColorEclipse produces a palette, Quickshell reads it, and the shell derives surfaces, borders, status colors and chart colors from it.
The color pipeline#
wallpaper image
│
▼
coloreclipse wal <path> # generate palette (or via the wallpaper picker)
│
▼
~/.cache/coloreclipse/colors.scss
│
├── Quickshell Theme.qml # bar, panels, launcher, lock screen
├── Qt apps # ~/.config/qt6ct/colors via qt6ct
└── greeter # normalized palette installed by the pickerColorEclipse is an external binary installed as coloreclipse-git from the AUR;
its source lives in a separate repository. The shell starts it at login with
coloreclipse apply and calls it when a workspace wallpaper is applied with
dynamic theme colors enabled.
Palette file#
Theme.qml watches ~/.cache/coloreclipse/colors.scss and parses:
background,foregroundaccentcolor0…color15(extended slots 9–15 may be absent)
Until the file exists, the shell uses built-in fallback colors. Missing extended slots are skipped by hue-based derivation, so an old palette does not break status colors.
The shell does not use color5 as the accent: it reads the binary's accent
entry, which is contrast-ranked. Derived tokens include surface,
surfaceHover, surfaceActive, border, muted, danger, success,
chart1..3, track and scrims. Text-bearing colors are contrast-fixed to
WCAG floors by the theme code.
Light and dark mode#
ColorEclipse owns the system light/dark variant:
coloreclipse get # prints the current variant
coloreclipse switch light # or: switch dark
coloreclipse apply # re-apply the generated themeThe control panel's theme toggle calls coloreclipse switch and refreshes the
cached state, so the shell, GTK/Qt apps and greeter stay in agreement. Settings
also contains:
| Setting | Default | Meaning |
|---|---|---|
| Dynamic Theme Colors | on | Regenerate palette when a wallpaper is applied |
| Dynamic Theme Variants | off | Allow ColorEclipse to choose light/dark from the wallpaper |
These are shell-side switches. ColorEclipse additionally reads
~/.config/coloreclipse/theme.conf for autocolor and autovariant, both
defaulting to true when the file is absent. The two layers are intentionally
separate: the shell decides whether to ask for a regeneration, ColorEclipse
decides what to do with the result.
Where colors are used#
| Surface | Consumer |
|---|---|
| Bar and panels | Theme.qml tokens, Settings.uiOpacity for translucency |
| Desktop apps | ColorEclipse writes GTK/Qt theme state; QT_QPA_PLATFORMTHEME=qt6ct |
| Terminal | Terminal palette regenerated by ColorEclipse |
| Cursor | HYPRCURSOR_SIZE = 24; the hyprcursor theme in ~/.config/hypr/cursors/ is copied to ~/.icons/ by the installer — only that theme renders, the phinger-cursors XCursor package serves GTK/XWayland |
| Icons | whitesur-icon-theme package |
| Greeter | The picker normalizes/installs colors.scss; sync-greeter.sh mirrors config and assets (excluding user data) to /etc/xdg/quickshell/archeclipse-greeter |
| Lock screen | Shell theme plus its own spring animations |
The Qt platform theme variable is set in
~/.config/hypr/config/env.lua; without it, Qt apps ignore the qt6ct palette
even when the package is installed.
Customizing the shell#
Semantic tokens#
theme/Theme.qml is the single source for colors, radii, spacing, type scale
and animation durations. Widgets consume tokens such as Theme.fg,
Theme.surface, Theme.accent, Theme.pad and Theme.anim.normal; they do
not hardcode hex colors. If you add QML, follow that rule or light/dark and
wallpaper changes will leave your widget behind.
Typography#
The shell uses the JetBrainsMono NFP family (installed by
ttf-jetbrains-mono-nerd) and a base size from Settings → Interface → Font
Size. Derived sizes are computed from that base. Changing the family is a code
change in theme/Theme.qml:
readonly property string fontFamily: "JetBrainsMono NFP"Hyprland decorations#
Window rounding, opacity, blur and shadow are in
~/.config/hypr/config/decoration.lua. The curated subset is editable from
Settings → Hyprland; everything else belongs in a custom Lua module:
-- ~/.config/hypr/config/custom/decoration_shadow.lua
hl.config({
decoration = {
shadow = { enabled = true, range = 18, render_power = 3 },
},
})Border colors need a nonzero general.border_size first. Set the color keys
using the Lua schema supported by your Hyprland build; TODO: add a verified
example for the current Hyprland Lua API.
Window effects and shaders#
Two GLSL shaders ship in config/shaders/: retro.glsl and
colors-broken-monitor.glsl. They are not enabled by the tracked config. Use
Hyprland's screen shader options in a custom module if you want them.
System theme components#
The installer's package list includes the pieces ColorEclipse drives:
libadwaita,gvfsqt6ctand a generated~/.config/qt6ct/colorspalettephinger-cursorswhitesur-icon-themettf-jetbrains-mono-nerd,noto-fonts-emoji
The exact GTK theme names and gsettings values are written by ColorEclipse, not
by this repository. Use coloreclipse switch and coloreclipse apply rather
than editing those files; they are regenerated.
Restarting the visual stack#
| Change | Action |
|---|---|
| Hyprland Lua change | hyprctl reload |
| Shell QML change | SUPER + B or lua ~/.config/hypr/config/scripts/bar.lua |
| Theme/palette | coloreclipse apply (or apply a wallpaper) |
| Greeter config mirror | bash ~/.config/quickshell/archeclipse/scripts/sync-greeter.sh |
| Wallpaper daemon | walleclipse reload |
If colors look wrong after a switch, verify the binary and palette:
coloreclipse get
ls -l ~/.cache/coloreclipse/colors.scss