Tone down README from dev-journal to description
Several sections had drifted into narrating the debugging process
("found the hard way", "confirmed via strace", listing out what was
tried and ruled out) instead of just stating the resulting facts. Kept
every actual technical gotcha, cut the discovery narrative around them.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dujsk9jYfxUVLtb5B8eC94
This commit is contained in:
28
README.md
28
README.md
@@ -72,14 +72,14 @@ Theming used to go through a third-party app called aether; it's gone now (it di
|
||||
|
||||
- [`theme/colors.toml`](theme/colors.toml) is the single source of truth for the palette: accent, cursor, foreground/background, 16 ANSI colors, four extra `*_color` fields (`bar_color`, `pill_color`, `popup_color`, `gtk_selection_color` — the terminal reuses `background`, already shared with mako), and five matching `*_opacity` floats (`bar_opacity`, `pill_opacity`, `popup_opacity`, `terminal_opacity`, `gtk_selection_opacity`, each 0-1)
|
||||
- [`theme/templates/<app>/`](theme/templates/) holds one `{config.json, template}` pair per themed app (Hyprland, Kitty, Rofi, mako, `gtk3`, `kde`, `kde-colorscheme`, `qt6ct`). `config.json` names the destination file; the template uses `{key}` placeholders (`{color4}`, `{background}`, `{accent}`, …), `{key.strip}` for the hex without `#`, `{key.rgb}` for `r,g,b` decimal with no alpha (what `kdeglobals` uses), or `{key.rgba:ALPHA}` for a `rgba(r, g, b, ALPHA)` string. Adding a new themed app is just adding one more folder here — no code changes
|
||||
- **`qt6ct` vs. `kdeglobals` vs. `kde-colorscheme`** — three templates that sound redundant but each theme a different layer, found the hard way while chasing why Dolphin's colors wouldn't take:
|
||||
- **`qt6ct` vs. `kdeglobals` vs. `kde-colorscheme`** — three templates that sound redundant but each theme a different layer:
|
||||
- `qt6ct` (`theme/templates/qt6ct/` → `~/.config/qt6ct/colors/aether-rice.conf`, a serialized `QPalette` — see the comment at the top of that template for the role-by-role mapping) is what a plain Qt6 app's own background/text/highlight colors actually come from, since `hyprland.lua` sets `QT_QPA_PLATFORMTHEME=qt6ct`
|
||||
- `kde` (`~/.config/kdeglobals`) matters for KDE/Plasma-integration bits, and for apps that read their own palette straight from it
|
||||
- `kde-colorscheme` (`~/.local/share/color-schemes/AetherRice.colors`) is the scheme `kdeglobals`'s `ColorScheme=AetherRice` line names — without an actual file there, KColorSchemeManager silently falls back to a stock scheme, and if the app's style happens to be Breeze (it loads alongside whatever `qt6ct.conf` says the style is; you can't assume it's off), some of *its* colors (e.g. item-view selection) come from here instead of `qt6ct`
|
||||
- Even with all three right, a real, currently-unresolved Dolphin regression ([KDE Discuss thread](https://discuss.kde.org/t/dolphin-how-can-i-override-the-new-highlight-color/38640)) hardcodes its selection color outside a full Plasma session no matter what — confirmed with `strace`, a known-good bundled qt6ct scheme, `QT_STYLE_OVERRIDE=Fusion`, and a `kbuildsycoca6` rebuild, none of which changed it. That's the actual reason Thunar replaced Dolphin here, not just a styling preference
|
||||
- **GTK3 (Thunar) has its own set of gotchas**, also found the hard way:
|
||||
- Even with all three right, Dolphin itself has a real, currently-unresolved regression ([KDE Discuss thread](https://discuss.kde.org/t/dolphin-how-can-i-override-the-new-highlight-color/38640)): it hardcodes its selection color outside a full Plasma session regardless of theme/style config. That's the actual reason Thunar replaced Dolphin here, not a styling preference
|
||||
- **GTK3 (Thunar) has its own set of gotchas:**
|
||||
- `!important` isn't just lower-priority in GTK3's CSS parser, it's rejected outright — every declaration using it gets dropped entirely ("Junk at end of value" under `GTK_DEBUG=interactive`). [`theme/templates/gtk3/gtk.css`](theme/templates/gtk3/gtk.css) has none; it doesn't need any, since `~/.config/gtk-3.0/gtk.css` already loads at `GTK_STYLE_PROVIDER_PRIORITY_USER`, above any theme's own CSS
|
||||
- The GTK3 *widget* theme (`gtk-theme-name`) and *icon* theme (`icon-theme`) resolve completely differently under Hyprland (no XSETTINGS daemon here). The widget theme needs [`gtk-3.0/settings.ini`](gtk-3.0/settings.ini) set directly; the icon theme is read straight from `gsettings`/dconf regardless (set in `hyprland.lua`'s `config.reloaded` hook) — putting it in `settings.ini` too does nothing, confirmed with `strace` showing which `folder.svg` actually got opened
|
||||
- The GTK3 *widget* theme (`gtk-theme-name`) and *icon* theme (`icon-theme`) resolve completely differently under Hyprland (no XSETTINGS daemon here). The widget theme needs [`gtk-3.0/settings.ini`](gtk-3.0/settings.ini) set directly; the icon theme is read straight from `gsettings`/dconf regardless (set in `hyprland.lua`'s `config.reloaded` hook) — putting it in `settings.ini` too does nothing
|
||||
- Thunar's grid is `ExoIconView`, an old widget that fetches its selection color as a named symbolic color (`gtk_style_context_lookup_color("theme_selected_bg_color")`) instead of through normal `:selected` CSS matching — `.view:selected` and even a blanket `*:selected` do nothing for it. The fix is redefining `@define-color theme_selected_bg_color`/`theme_selected_fg_color` (+ the `unfocused_` pair) in `gtk.css`, which is what `gtk_selection_color`/`gtk_selection_opacity` actually drive
|
||||
- Folder icon *colors* aren't CSS at all — they're baked into the icon theme's SVGs. [`theme/icon_theme.py`](theme/icon_theme.py) generates a small icon theme at `~/.local/share/icons/AetherRice` (inheriting Papirus-Dark for everything else) by taking Papirus-Dark's own "blue" folder SVGs and substituting their two fixed colors for the accent and a darkened variant — no sudo needed, and it matches the accent exactly rather than snapping to one of `papirus-folders`' fixed presets
|
||||
- [`theme/render.py`](theme/render.py) renders every template to its destination and reloads the affected apps (`hyprctl reload`, `makoctl reload`, kitty via `SIGUSR1`, a best-effort `dbus-send` KGlobalSettings ping for KDE apps). Qt/GTK apps only read their palette/CSS at startup, and not every app listens for the `dbus-send` ping either — an already-open window generally keeps its old colors until it's restarted, a freshly launched one picks up a palette change immediately. It also pings the running shell over Quickshell's two IPC targets (`theme` for the bar, `theme-widget` for the widget itself — two separate top-level QML components) so the bar's own accent/border/pill colors and all four opacities, which live in QML rather than a config file another app reads, pick up changes immediately too — no restart. Run it after editing a template by hand, or use `--set KEY VALUE` to change one color (`#rrggbb`) or opacity (`0`-`1`) from a terminal, `--get KEY` / `--dump` to read the palette back out
|
||||
@@ -102,11 +102,11 @@ After that, `theme/render.py` (called by the widget on every palette change, sam
|
||||
Wallpaper changes need the same sync: `theme/wallpaper.py` doesn't go through `render.py` at all normally, so it calls `render.sync_sddm_theme()` itself directly at the end of `restart_wallpaper_daemon()` - without that, picking a new wallpaper in the widget would silently leave the login screen on the old one.
|
||||
|
||||
Things specific to SDDM that don't come up anywhere else in this rice:
|
||||
- **Each connected monitor gets its own separate `Main.qml` instance** (confirmed with `sddm-greeter --test-mode`, two monitors, two windows) with its own local coordinate space - a `screenModel`-with-manual-geometry-offset approach (the pattern used in SDDM's own bundled `maya` theme) would push each screen's background out of that screen's own view. Plain `anchors.fill: parent` is what actually works here. The login card itself is only shown where the `primaryScreen` context property is true, so a dual-monitor setup gets exactly one card, not one per screen.
|
||||
- **Each connected monitor gets its own separate `Main.qml` instance**, each with its own local coordinate space - a `screenModel`-with-manual-geometry-offset approach (the pattern used in SDDM's own bundled `maya` theme) pushes each screen's background out of that screen's own view instead. Plain `anchors.fill: parent` is what actually works here. The login card itself is only shown where the `primaryScreen` context property is true, so a dual-monitor setup gets exactly one card, not one per screen.
|
||||
- **Which monitor SDDM considers primary defaults to whichever it enumerates first, not the biggest one.** `sddm/aether-rice/Xsetup` (wired up as `DisplayCommand` above) runs `xrandr --output <output> --primary` before the greeter starts to fix that - `<output>` is picked dynamically as whichever connected output has the largest resolution, not hardcoded, since Xorg (particularly with the nvidia driver, in use here) often names outputs differently than Wayland/DRM does (e.g. `DP-0` vs. Hyprland's `DP-1`) - a name copied from `hyprctl monitors` can silently match nothing in the greeter's own X server. It logs what it found and did to `/tmp/aether-rice-xsetup.log` for the next login if it ever needs re-diagnosing.
|
||||
- **`SddmComponents`' `ComboBox`/`LayoutBox` open their dropdown as a plain child `Rectangle` anchored below themselves, not an actual popup** - it paints under whatever comes later in the same `Column`, not over it. The session/layout row is the last thing in the card for exactly this reason; putting it anywhere earlier (e.g. above the Login button, as originally built) gets its dropdown list rendered underneath - technically open, but invisible and unclickable behind the buttons below it.
|
||||
- **`SddmComponents`' `ComboBox`/`LayoutBox` open their dropdown as a plain child `Rectangle` anchored below themselves, not an actual popup** - it paints under whatever comes later in the same `Column`, not over it. The session/layout row is the last thing in the card for exactly this reason; putting it anywhere earlier (e.g. above the Login button) gets its dropdown list rendered underneath - technically open, but invisible and unclickable behind the buttons below it.
|
||||
- **`SddmComponents`' own `Button` can get its background stuck on the wrong color** (e.g. hover) instead of reverting to idle - it drives color through named QML `states`, and once something sets `color` outside that state machine, the idle state has nothing correct left to revert to. `Main.qml`'s Login/Shutdown/Reboot buttons are plain `Rectangle` + `MouseArea` instead, with color bound directly to `containsMouse` - no state machine, nothing to get stuck.
|
||||
- **The keyboard layout shows/applies as the wrong one until the first keypress, every time.** This is a confirmed, still-open upstream SDDM 0.21 bug ([sddm/sddm#1845](https://github.com/sddm/sddm/issues/1845)), reproducible with every theme including SDDM's own bundled ones (the maintainer asked reporters to test other themes - same result on all of them). Nothing in a theme's QML can fix a backend bug; two different `keyboard.currentLayout` reassignment workarounds were tried here and removed again since neither helped.
|
||||
- **The keyboard layout shows/applies as the wrong one until the first keypress, every time.** Confirmed, still-open upstream SDDM 0.21 bug ([sddm/sddm#1845](https://github.com/sddm/sddm/issues/1845)), reproducible on every theme including SDDM's own bundled ones — a backend bug, not something a theme's QML can work around (reassigning `keyboard.currentLayout` doesn't fix it).
|
||||
|
||||
`sddm-greeter --test-mode --theme <path>` can't verify everything: `sddm.hostName` comes back empty in test mode (no real greeter daemon behind it), so the heading shows "Welcome to" with nothing after it there specifically - expected to resolve once it's actually running as the login screen. Multi-monitor primary selection and the keyboard layout bug above need an actual logout to check, since test-mode doesn't run a real X server per screen or a real XKB backend.
|
||||
|
||||
@@ -128,13 +128,13 @@ sudo gpasswd -a "$USER" openrazer
|
||||
# then reboot
|
||||
```
|
||||
|
||||
Found the hard way:
|
||||
Notable quirks:
|
||||
- **The mouse's USB product ID is different over its cable vs. its wireless dongle** (`1532:00C0` vs `1532:00C1` here) — openrazer-daemon only scans for devices at its *own* startup, not on hotplug, so switching cable↔dongle while it's already running goes completely unnoticed. `mouse.py` detects an empty device list and restarts `openrazer-daemon` once via `systemctl --user restart` before giving up, which picks the switch up within one call instead of needing a manual restart.
|
||||
- **The low-battery threshold is hardware-capped at 25%**, confirmed by testing every value 0-100 against the real device — asking for more just silently clamps to 25, undocumented anywhere. The widget's slider range reflects that cap instead of pretending 0-100 works.
|
||||
- **The DPI reset to a generic default (1800) the first time OpenRazer's daemon ever bound to the device**, overwriting whatever had been configured before (e.g. via Razer Synapse on a Windows dual-boot) — `restore_persistence` defaults to `false`, so the daemon doesn't restore anything on its own, it just starts the device off wherever its driver-level init leaves it. The device's 5 *stored* DPI stages survived this untouched, which is how the original value got found again (the stage list's reported "active index" still pointed at it, even though the single live `.dpi` reading didn't match any of them).
|
||||
- **A confirmed, still-open upstream SDDM bug** affects this mouse too, incidentally: see the keyboard-layout bullet in the SDDM section above — unrelated hardware, same "backend doesn't apply state until first input" shape.
|
||||
- **The low-battery threshold is hardware-capped at 25%** — asking for more just silently clamps to 25, undocumented anywhere. The widget's slider range reflects that cap instead of pretending 0-100 works.
|
||||
- **The DPI resets to a generic default (1800) the first time OpenRazer's daemon ever binds to the device**, overwriting whatever had been configured before (e.g. via Razer Synapse on a Windows dual-boot) — `restore_persistence` defaults to `false`, so the daemon doesn't restore anything on its own, it just starts the device off wherever its driver-level init leaves it. The device's 5 *stored* DPI stages survive this untouched, so the original value is still recoverable from there (the stage list's reported "active index" still points at it, even when the single live `.dpi` reading doesn't match any of them).
|
||||
- **The same still-open upstream SDDM bug noted above affects this mouse too**, incidentally — unrelated hardware, same "backend doesn't apply state until first input" shape.
|
||||
|
||||
Unrelated to OpenRazer, but found while setting it up: `hyprland.lua`'s `input` block never set `accel_profile`, so Hyprland/libinput were using their own default adaptive (accelerated) curve the whole time rather than the flat/linear response a gaming mouse is normally run with - only actually noticeable once the DPI reset above changed how it felt. Now `accel_profile = "flat"`.
|
||||
Also unrelated to OpenRazer but found while setting it up: `hyprland.lua`'s `input` block never set `accel_profile`, so Hyprland/libinput were using their own default adaptive (accelerated) curve — not the flat/linear response a gaming mouse is normally run with. Now `accel_profile = "flat"`.
|
||||
|
||||
**RGB** ([`RGBWidget.qml`](quickshell/default/RGBWidget.qml) + [`scripts/rgb.py`](quickshell/default/scripts/rgb.py)) — per-device mode (Direct/Rainbow/Breathing/…), color, speed, and brightness (wherever the active mode supports them) for RAM (Corsair Vengeance RGB Pro ×2, shown and controlled as *one* card since they're the same model - `rgb.py`'s commands all accept a comma-separated list of device IDs), GPU (Gigabyte RTX 3060 Gaming OC), and mainboard (ASUS ROG STRIX B550-F, Aura) — plus a "Sync all to accent" button that's the actual point of having this at all. All three go through [OpenRGB](https://openrgb.org/)'s SDK server, autostarted headless (`openrgb --server`, in `hyprland.lua`) so the widget's queries are fast — the plain CLI re-detects all hardware (~5s) on every single invocation, which is too slow to poll.
|
||||
|
||||
@@ -145,9 +145,9 @@ echo i2c-dev | sudo tee /etc/modules-load.d/i2c-dev.conf # persist across rebo
|
||||
yay -S python-openrgb # AUR - the SDK client library rgb.py imports
|
||||
```
|
||||
|
||||
Found the hard way:
|
||||
Notable quirks:
|
||||
- **This exact server build (`openrgb` 1.0-2, Arch `extra`) doesn't handle `openrgb-python`'s default SDK protocol version (4) correctly** — the plugin-list request it sends during connection setup just hangs until the client's socket times out. `rgb.py` connects with `protocol_version=3` explicitly, which skips that request and works.
|
||||
- **Setting a color doesn't reliably switch the device to Direct mode first** — a device left on a cycling mode (Rainbow Wave, Spectrum Cycle, …) can keep animating straight through a `set_color()` call, so the static color never actually sticks despite the API call succeeding and even reporting back the "right" state immediately after. Intermittent, not consistently reproducible - looks like SMBus/i2c timing flakiness, worst on the GPU specifically (its own NVIDIA i2c adapter, not the mainboard/RAM's shared SMBus one). `rgb.py`'s `set_color()` explicitly forces Direct mode first, waits, then re-reads the live state and retries once if it doesn't match what was asked for.
|
||||
- **Setting a color doesn't reliably switch the device to Direct mode first** — a device left on a cycling mode (Rainbow Wave, Spectrum Cycle, …) can keep animating straight through a `set_color()` call, so the static color never actually sticks despite the API call succeeding and even reporting back the "right" state immediately after. Intermittent SMBus/i2c timing flakiness, worst on the GPU (its own NVIDIA i2c adapter, not the mainboard/RAM's shared SMBus one). `rgb.py`'s `set_color()` explicitly forces Direct mode first, waits, then re-reads the live state and retries once if it doesn't match what was asked for.
|
||||
|
||||
## Hotkeys
|
||||
|
||||
|
||||
Reference in New Issue
Block a user