docs: spec for waybar tray drawer (collapsible icons)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-30 21:14:13 -07:00
parent 7ab5116e5d
commit 412034ea9f
1 changed files with 93 additions and 0 deletions
@@ -0,0 +1,93 @@
+# Waybar Tray Drawer Design
+
+**Date:** 2026-04-30
+**Status:** Approved
+
+## Summary
+
+Add a Windows-style "show hidden icons" arrow to the waybar system tray. By default the tray icons are collapsed behind a single chevron glyph; clicking the chevron expands them inline to its right with a short slide animation. Clicking again collapses them back. No custom scripting — implemented entirely with waybar's built-in `group/drawer` module.
+
+## Current Behaviour
+
+The `tray` module sits at the rightmost end of `modules-right` and always shows every status-icon a running program emits. When several apps are running (Discord, Steam, mouse manager, syncthing, etc.) the tray takes up significant horizontal space.
+
+## Target Behaviour
+
+```
+collapsed:    ... battery   [>]
+expanded:     ... battery   [<] [icon][icon][icon]
+```
+
+- Default state on bar startup: collapsed (only the arrow visible).
+- Click the arrow → tray icons appear to its right, ~200 ms slide.
+- Click the arrow again → tray icons collapse.
+- Tray icons keep their normal click/scroll behaviour while expanded.
+- State is per-bar-session; no persistence across waybar restarts.
+
+## Implementation
+
+### `waybar/config.jsonc`
+
+Replace `"tray"` in `modules-right` with `"group/tray-drawer"`. Add the group definition and the chevron module:
+
+```jsonc
+"modules-right": [
+  "cpu", "temperature", "custom/power-profile", "custom/fan-profile",
+  "pulseaudio", "network", "battery", "custom/mouse-battery",
+  "group/tray-drawer"
+],
+
+"group/tray-drawer": {
+  "orientation": "horizontal",
+  "drawer": {
+    "transition-duration": 200,
+    "children-class": "tray-drawer-child",
+    "transition-left-to-right": true,
+    "click-to-reveal": true
+  },
+  "modules": ["custom/tray-arrow", "tray"]
+},
+
+"custom/tray-arrow": {
+  "format": "",
+  "tooltip": false
+}
+```
+
+The arrow is the first module in the group, so it stays visible when collapsed; `tray` is revealed/hidden by the drawer.
+
+Glyph `` is `nf-fa-chevron_right` from Nerd Fonts. Pointing right when collapsed reads as "more stuff is hidden over here — click to reveal"; CSS rotates it to point left when expanded, signalling "click to put it back".
+
+### `waybar/style.css`
+
+Add styling for the chevron and a rotation rule keyed off the drawer's expanded state:
+
+```css
+#custom-tray-arrow {
+  padding: 0 8px;
+  color: @fg-dim;
+  transition: transform 200ms ease;
+}
+
+#group-tray-drawer.expanded #custom-tray-arrow {
+  transform: rotate(180deg);
+}
+```
+
+Reuse the existing dim foreground colour variable so the arrow blends with other inactive-state glyphs and doesn't read as a status icon. Match `transition-duration` to the drawer's 200 ms.
+
+### Compatibility
+
+`click-to-reveal` was added in waybar 0.10. Installed version is 0.15.0 — supported.
+
+## Files Touched
+
+- `waybar/config.jsonc` — replace `tray` entry, add two module definitions
+- `waybar/style.css` — add `#custom-tray-arrow` rules
+
+## Out of Scope
+
+- Persisting expanded/collapsed state across waybar restarts
+- Per-icon hide/show (waybar's `tray` module is monolithic — all icons or none)
+- Animating the surrounding modules; they shift left to make room as the drawer opens, which is unavoidable with waybar's drawer
+- Extending the same pattern to other right-side modules