Skip to content
ArchEclipse

Common pages

↑↓to navigate↵to openescto close
Theming and Customization
On this page

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#

text
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 picker

ColorEclipse 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, foreground
  • accent
  • color0 … 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:

bash
coloreclipse get              # prints the current variant
coloreclipse switch light     # or: switch dark
coloreclipse apply             # re-apply the generated theme

The 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:

SettingDefaultMeaning
Dynamic Theme ColorsonRegenerate palette when a wallpaper is applied
Dynamic Theme VariantsoffAllow 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#

SurfaceConsumer
Bar and panelsTheme.qml tokens, Settings.uiOpacity for translucency
Desktop appsColorEclipse writes GTK/Qt theme state; QT_QPA_PLATFORMTHEME=qt6ct
TerminalTerminal palette regenerated by ColorEclipse
CursorHYPRCURSOR_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
Iconswhitesur-icon-theme package
GreeterThe picker normalizes/installs colors.scss; sync-greeter.sh mirrors config and assets (excluding user data) to /etc/xdg/quickshell/archeclipse-greeter
Lock screenShell 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:

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:

lua
-- ~/.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, gvfs
  • qt6ct and a generated ~/.config/qt6ct/colors palette
  • phinger-cursors
  • whitesur-icon-theme
  • ttf-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#

ChangeAction
Hyprland Lua changehyprctl reload
Shell QML changeSUPER + B or lua ~/.config/hypr/config/scripts/bar.lua
Theme/palettecoloreclipse apply (or apply a wallpaper)
Greeter config mirrorbash ~/.config/quickshell/archeclipse/scripts/sync-greeter.sh
Wallpaper daemonwalleclipse reload

If colors look wrong after a switch, verify the binary and palette:

bash
coloreclipse get
ls -l ~/.cache/coloreclipse/colors.scss