diff options
Diffstat (limited to 'SPEC.md')
| -rw-r--r-- | SPEC.md | 208 |
1 files changed, 208 insertions, 0 deletions
@@ -0,0 +1,208 @@ +# waybar-theme-udt + +A waybar bar for DP-3, themed by [unified-desktop-theme][udt] and drawn with +icons from the desktop's own icon theme rather than font glyphs. + +[udt]: ../unified-desktop-theme + +## Goal + +Three things at once: + +- **No font glyphs.** Every module that shows a symbol shows a real icon from + `Material-Black-Plum-Suru`, the theme GTK already uses. Icons keep their own + colours, because that is what every other application on this desktop shows. +- **Colours from udt.** Pill backgrounds, text and states resolve from + `palette/roles-<scheme>.conf`, so switching scheme recolours this bar with + everything else. +- **Pill clusters with transitions.** The grouped-capsule layout of `idea1.png` + with the hover and state transitions of `idea2.png`. + +The current bar on DP-1 is untouched. This one installs alongside it and is +pointed at DP-3. + +## Layout + + ┌ left ──────────────────────────────┐ ┌ center ┐ ┌ right ─────────────────────┐ + [◆] [📅 Wed 15/09] [🕑 14:32] [1..8] [●●] [ open apps ] [🔊 62%] [tray] [⏻] [🇮🇹] + launcher date time workspaces vm taskbar volume tray present lang + +Each bracket is one pill. Neighbouring pills in a cluster share a background +and weld together with asymmetric corner radii; clusters are separated by +transparent gaps, so the bar reads as groups rather than a continuous strip. + +### Modules + +| Position | Module | Icon source | Notes | +| --- | --- | --- | --- | +| left | `custom/launcher` | `slackware.svg`, shipped here | Accent background, the one always-coloured pill. Opens the quickshell drawer. | +| left | `clock#date` | `x-office-calendar` | Icon then text. Calendar tooltip kept. | +| left | `clock#time` | `clock` | Icon then text. | +| left | `hyprland/workspaces` | eight themed icons, via CSS | See below. | +| left | `custom/vmdot` | coloured dots | Dots keep their shape; colours move to roles. | +| center | `wlr/taskbar` | `icon-theme` config key | Per-window application icons. | +| right | `group/wireplumber` | `image` module | Drawer group kept as it is today. | +| right | `tray` | application-provided | | +| right | `idle_inhibitor` | `image` module | Presentation mode. | +| right | `image#lang` | `flag-it.svg` / `flag-gb.svg`, shipped here | An `image` module: `hyprland/language` styles as `#language` only, with no per-language class, so a flag cannot be selected in CSS. | + +Dropped from the current bar: `custom/breaktimer`, `custom/mail`, +`custom/privacy_dots` stays only if you want it on this bar too (it is +currently listed; say if it should follow the others out). No battery, no +temperature, no cpu, no memory, no backlight: this is a desktop. + +Clock is the one module that stays text. An icon cannot say 14:32; the icon +sits before the text, which is what makes it match the rest. + +### Workspace icons + +| WS | Icon | Was | +| --- | --- | --- | +| 1 | `web-browser` | browser glyph | +| 2 | `utilities-terminal` | terminal glyph | +| 3 | `text-editor` | code glyph | +| 4 | `network-server` | matches the quickshell drawer's VM tile (`U+F233`, Font Awesome `server`) | +| 5 | `document-edit` | pen on a document: the alternate text editor lives here | +| 6 | `applications-graphics` | graphics glyph | +| 7 | `internet-chat` | chat glyph | +| 8 | `input-gaming` | joypad: games and media players | + +All eight resolve in `Material-Black-Plum-Suru` today. + +## How icons reach the bar + +Three mechanisms, because waybar offers three and no single one covers +everything. This is the part worth reading before changing anything. + +**1. Native `icon-theme` (taskbar, tray).** `wlr/taskbar` takes `icon-theme` +and `icon-size` outright. Today it asks for `Papirus`, **which is not +installed**, so GTK has been silently falling back. Pointing it at +`Material-Black-Plum-Suru` is a bug fix, not a preference. + +**2. The `image` module (volume, presentation mode).** `image` runs `exec` and +expects `$path\n$tooltip` on stdout, so a small script maps state to an icon +name, resolves it through the GTK icon theme, and prints the path. One `image` +module is one icon, so a five-state volume indicator is one module plus one +script, not five modules. + +**3. CSS `background-image` (workspaces).** Workspace buttons come from a +single `hyprland/workspaces` module and `format-icons` takes text, not paths. +Faking the strip with eight `custom` modules would lose click-to-switch and +the active/urgent states, so instead the real module keeps its behaviour, its +labels are emptied, and each button gets an icon through +`#workspaces button:nth-child(n) { background-image: url(...) }`. + +The consequence, stated plainly: **the eight workspace icon paths live in the +stylesheet, not in the config.** Changing a workspace icon means editing CSS. + +### Why the icons cannot follow the accent + +2466 of the 5169 panel icons in `Material-Black-Plum-Suru` carry a hardcoded +`oomox` gradient (`#a08fbf` to `#5a33a3`) and seven further named gradients +each. They are not monochrome and not recolourable by CSS `color`. So icons +show their own colours and do not track the scheme, which is the intended +behaviour here: they match every other application on the desktop. + +The two icons this repo ships are the exception. `slackware.svg` (from +Simple Icons) and the two flags are single-path monochrome, so `slackware.svg` +is tinted with the udt accent by a one-line `fill` substitution at install +time. The flags keep their national colours. + +## Repository layout + +Modular, one file per module, mirroring the current setup: + + config.jsonc entry point, `include`s every module file + modules/ + clock.jsonc clock#date and clock#time + hyprland/ + workspaces.jsonc + language.jsonc + custom/ + launcher.jsonc + vmdot.jsonc + extras/ + taskbar.jsonc + tray.jsonc + wireplumber.jsonc + image/ + idle_inhibitor.jsonc presentation mode, via `image` + styles/ + style.css entry point, imports the rest in order + theme.css GENERATED by udt-palette, gitignored + fonts.css + global.css #waybar, tooltip, button base rules + pills.css the cluster geometry and transitions + modules.css per-module rules, including workspace icons + icons/ + slackware.svg carries @ACCENT@, substituted on install + flag-it.svg + flag-gb.svg + bin/ + wb-icon state to icon path, for the `image` modules + vms_dots.sh moved here from ~/bin, symlinked back + privacy_dots.sh moved here from ~/bin, symlinked back + install.sh + LICENSE + README.md + +Wildcard `include` is broken in waybar 0.14, so `config.jsonc` lists every +module file explicitly. That is a waybar limitation, not a choice. + +## Palette integration + +This repo is a **consumer** of udt: it holds the bar, udt holds the colours. + +`styles/theme.css` is generated by `udt-palette` and gitignored, exactly like +every other generated file in that repo. Generating it needs two changes on +the udt side: + +**A new `[waybar]` role block.** The current one names `temperature`, +`memory`, `cpu`, `backlight` and `battery`, none of which exist on this bar. +The new roles are `launcher`, `workspaces`, `vmdots`, `taskbar`, `volume`, +`tray`, `present`, `lang`, `date`, `time`, plus the existing `main_*`, +`hover_*` and `outline`. + +**Added to all nine `roles-*.conf`.** `udt-palette --selftest` enforces that +every scheme defines the same role set, so a role added to one file and not +the rest fails the check. That is the check doing its job. + +Dot colours come from the existing `[state]` roles: `success` for a running +VM, `warning` for paused, `critical` for crashed, `info` for saved, and +`fg_faint` for shut off. Both dot scripts currently hardcode `#30D158`, +`#FFD60A`, `#FF9F0A`, `#9B32FA` and `#6E6E73`; they will read a generated +colour block instead. + +## Install + +`install.sh` follows udt's conventions: symlink what this repo owns +canonically, copy what another application owns, guard every reload. + +- Module and style files are **symlinked** into `~/.config/waybar-udt/`, so the + repo cannot drift from what is installed. +- `icons/slackware.svg` is **generated** into place with `@ACCENT@` substituted, + the same way udt generates `launcher.rasi`. +- `bin/vms_dots.sh` and `bin/privacy_dots.sh` are symlinked to `~/bin/`, + replacing the copies that live there now. **The originals are backed up + first**: they are the only copy and are not currently in any repository. +- The bar is **not** started and `~/.config/waybar` is **not** touched. Running + it is one command, printed at the end, so DP-1's bar keeps working until you + choose otherwise. + +Reload is `killall -SIGUSR2 waybar`, and `reload_style_on_change` is already on. + +## Verification + +Per udt's own rule, visual claims are measured, not reasoned about: + + grim -o DP-3 /tmp/shot.png + +`wb-icon` gets one runnable self-check: every icon name the bar asks for must +resolve in the icon theme, so a missing icon fails loudly at install time +rather than rendering as a blank pill. + +## Open questions + +1. `custom/privacy_dots` is in the keep list but was not in the ten modules you + named. On this bar or not? +2. Licence: GPLv2-only unless you say otherwise. |