repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

test(quickshell): audit nugu theme contrast

59bceb3e2dafad99f1389f645a2f268329bf1cbb

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

docs/super/inventory/2026-06-17-quickshell-self-contained-audit.md

Modified
21 21 - local resource references are audited; currently only bundled `nugu.json` is allowed via `Qt.resolvedUrl`.
22 22 - live/repo path markers such as `../`, `~/.config`, and `~/.local` fail the audit.
23 23 - `quickshell/nugu/nugu.json` exists and matches `hypr/generated/nugu.json`.
24 +- critical Nugu dark/light foreground/background pairs keep at least 4.5 contrast.
24 25 - executable code does not call retired companion app markers:
25 26 - `hyprlauncher`
26 27 - `hyprshutdown`
51 52 ipc_methods=58
52 53 documented_ipc=58
53 54 documented_external_commands=25
55 +contrast_pairs=12
56 +contrast_min=5.50
54 57 required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,audit.sh,smoke.sh
55 58 external_commands=awk,brightnessctl,cliphist,cut,grep,head,hyprctl,hyprlock,hyprpicker,hyprshot,iwctl,loginctl,makoctl,nu,playerctl,satty,sed,sh,systemctl,upower,uptime,uwsm,wezterm,wl-copy,wpctl
56 59 WARN transitional external bridge still present: cliphist
62 65 ipc_methods=58
63 66 documented_ipc=58
64 67 documented_external_commands=25
68 +contrast_pairs=12
69 +contrast_min=5.50
65 70 required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,audit.sh,smoke.sh
66 71 external_commands=awk,brightnessctl,cliphist,cut,grep,head,hyprctl,hyprlock,hyprpicker,hyprshot,iwctl,loginctl,makoctl,nu,playerctl,satty,sed,sh,systemctl,upower,uptime,uwsm,wezterm,wl-copy,wpctl
67 72 WARN transitional external bridge still present: cliphist

quickshell/nugu/README.md

Modified
32 32 that required named-config files are present, every QML component and IPC method
33 33 are documented, QML imports stay local/Qt/Quickshell, every component has an
34 34 early decision comment, local resources are audited, the bundled palette matches
35 -`hypr/generated/nugu.json`, external commands are documented, and retired
36 -companion launchers are not executable dependencies. It intentionally warns while
35 +`hypr/generated/nugu.json`, critical Nugu foreground/background pairs keep at
36 +least 4.5 contrast, external commands are documented, and retired companion
37 +launchers are not executable dependencies. It intentionally warns while
37 38 transitional `cliphist` and `makoctl` bridges remain; those warnings must
38 39 disappear before final retirement.

quickshell/nugu/audit.sh

Modified
10 10 python - "$config_dir" "$repo_dir" <<'PY'
11 11 from pathlib import Path
12 +import json
12 13 import re
13 14 import sys
103 104 palette = config_dir / "nugu.json"
104 105 generated = repo_dir / "hypr" / "generated" / "nugu.json"
106 +contrast_pairs = []
105 107 if not palette.exists():
106 108 errors.append("missing bundled nugu.json")
107 -elif generated.exists() and palette.read_text() != generated.read_text():
108 - errors.append("quickshell/nugu/nugu.json differs from hypr/generated/nugu.json")
109 +else:
110 + if generated.exists() and palette.read_text() != generated.read_text():
111 + errors.append("quickshell/nugu/nugu.json differs from hypr/generated/nugu.json")
113 + def linear(channel):
114 + value = channel / 255
115 + return value / 12.92 if value <= 0.04045 else ((value + 0.055) / 1.055) ** 2.4
117 + def luminance(hex_color):
118 + value = hex_color.lstrip("#")
119 + red = int(value[0:2], 16)
120 + green = int(value[2:4], 16)
121 + blue = int(value[4:6], 16)
122 + return 0.2126 * linear(red) + 0.7152 * linear(green) + 0.0722 * linear(blue)
124 + def contrast(foreground, background):
125 + front = luminance(foreground)
126 + back = luminance(background)
127 + light = max(front, back)
128 + dark = min(front, back)
129 + return (light + 0.05) / (dark + 0.05)
131 + try:
132 + palettes = json.loads(palette.read_text())
133 + for mode in ("dark", "light"):
134 + colors = palettes[mode]
135 + content = colors["content"]
136 + ui = colors["ui"]
137 + checks = {
138 + "content.normal/content.backdrop": (content["normal"], content["backdrop"]),
139 + "content.minor/content.backdrop": (content["minor"], content["backdrop"]),
140 + "ui.normal/ui.backdrop": (ui["normal"], ui["backdrop"]),
141 + "ui.minor/ui.backdrop": (ui["minor"], ui["backdrop"]),
142 + "content.backdrop/ui.focus": (content["backdrop"], ui["focus"]),
143 + "content.backdrop/ui.accent": (content["backdrop"], ui["accent"]),
145 + for label, (foreground, background) in checks.items():
146 + ratio = contrast(foreground, background)
147 + contrast_pairs.append((mode, label, ratio))
148 + if ratio < 4.5:
149 + errors.append(f"{mode} contrast {label} is {ratio:.2f}, below 4.5")
150 + except (KeyError, ValueError, json.JSONDecodeError) as error:
151 + errors.append(f"invalid Nugu palette for contrast audit: {error}")
110 153 # Keep executable dependencies explicit. Quickshell can replace companion UI,
111 154 # but system/session CLIs still exist at command boundaries until later parity
164 207 print(f"ipc_methods={len(ipc_methods)}")
165 208 print(f"documented_ipc={len(documented_ipc)}")
166 209 print(f"documented_external_commands={len(external_commands)}")
210 +print(f"contrast_pairs={len(contrast_pairs)}")
211 +if contrast_pairs:
212 + print(f"contrast_min={min(ratio for _mode, _label, ratio in contrast_pairs):.2f}")
167 213 print("required_files=" + ",".join(required_files))
168 214 if detected:
169 215 print("external_commands=" + ",".join(command for command, _reason in detected))