repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit nugu style contract

cc63e36f4ff5e0f64a0801ed3916232539764fd4

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (4)

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

Modified
13 13 `quickshell/nugu/audit.sh` checks repository state only:
15 -- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `TRANSITIONS.md`, `SERVICE.md`, `PARITY.md`, `HYPR_MIGRATION.md`, `ROLLOUT.md`, `PERF.md`, `audit.sh`, `smoke.sh`, `live-check.sh`.
15 +- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `TRANSITIONS.md`, `SERVICE.md`, `PARITY.md`, `HYPR_MIGRATION.md`, `ROLLOUT.md`, `PERF.md`, `STYLE.md`, `audit.sh`, `smoke.sh`, `live-check.sh`.
16 16 - `README.md` links the required inventories, service/parity contracts, smoke/audit/live-check gates, named config command, and IPC command form.
17 17 - `live-check.sh` is executable and audited read-only: it must not link, start, stop, enable, disable, restart, or launch `qs -c nugu`.
18 18 - `smoke.sh` is executable and audited for self-contained temp `HOME`/`XDG_CONFIG_HOME`, named config launch, launcher/clipboard/power/native-notification/OSD IPC probes, cleanup trap, and no live link/service mutation.
24 24 - future service rollout is documented in `SERVICE.md`; `hypr/systemd/quickshell.service` must start `qs -c nugu`, and `x230.symlinks` must link both config and service.
25 25 - `ROLLOUT.md` must keep approval-only cutover, rollback, DBus, old-service, and final-completion boundaries visible.
26 26 - `PERF.md` must document every current polling/action process budget and the future live performance evidence gate.
27 +- `STYLE.md` must document Nugu semantic roles, IBM Plex-only fonts, no hard-coded component hex colors, and the human visual approval boundary.
27 28 - replacement scope is documented in `PARITY.md`, including old companion retirement targets, non-thin row statuses/gates, valid QML replacement references, human approval, and the explicit “not complete / old tools remain authoritative” boundary.
28 29 - Hypr simplification is documented in `HYPR_MIGRATION.md`; rows must cover old helper markers from the current Hypr modules and point only at existing `nugu` IPC methods.
29 30 - QML imports are limited to Qt, Quickshell, and local `import "."`.
79 80 parity_rows=12
80 81 perf_rows=12
81 82 perf_budget=ok
83 +style_font_refs=23
84 +style_hex_refs=20
85 +style_contract=ok
82 86 rollout_runbook=ok
83 87 hypr_migration_rows=21
84 88 hypr_current_refs=8
86 90 rollout_boundary=ok
87 91 contrast_pairs=12
88 92 contrast_min=5.50
89 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,HYPR_MIGRATION.md,ROLLOUT.md,PERF.md,audit.sh,smoke.sh,live-check.sh
93 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,HYPR_MIGRATION.md,ROLLOUT.md,PERF.md,STYLE.md,audit.sh,smoke.sh,live-check.sh
90 94 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
91 95 WARN transitional external bridge still present: cliphist
92 96 WARN transitional external bridge still present: makoctl
111 115 parity_rows=12
112 116 perf_rows=12
113 117 perf_budget=ok
118 +style_font_refs=23
119 +style_hex_refs=20
120 +style_contract=ok
114 121 rollout_runbook=ok
115 122 hypr_migration_rows=21
116 123 hypr_current_refs=8
118 125 rollout_boundary=ok
119 126 contrast_pairs=12
120 127 contrast_min=5.50
121 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,HYPR_MIGRATION.md,ROLLOUT.md,PERF.md,audit.sh,smoke.sh,live-check.sh
128 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,HYPR_MIGRATION.md,ROLLOUT.md,PERF.md,STYLE.md,audit.sh,smoke.sh,live-check.sh
122 129 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
123 130 WARN transitional external bridge still present: cliphist
124 131 WARN transitional external bridge still present: makoctl

quickshell/nugu/README.md

Modified
34 34 documents the future user-service rollout contract without activating it.
35 35 `ROLLOUT.md` documents the approval-only cutover and rollback sequence.
36 36 `PERF.md` inventories polling/action process budgets and the future live perf gate.
37 +`STYLE.md` records the audited Nugu style/font/color contract.
37 38 `PARITY.md` maps current companion apps/tools to their Quickshell replacements
38 39 and retirement gates. `HYPR_MIGRATION.md` maps current Hypr binds/helpers to
39 -future Quickshell IPC targets. `live-check.sh` reports final rollout blockers, including old Hypr companion refs, without mutating live services or links. The audit checks that required named-config files are present, the rollout runbook keeps approval/rollback boundaries visible, the performance budget documents every polling/action boundary, every QML component and IPC method
40 +future Quickshell IPC targets. `live-check.sh` reports final rollout blockers, including old Hypr companion refs, without mutating live services or links. The audit checks that required named-config files are present, the rollout runbook keeps approval/rollback boundaries visible, the performance budget documents every polling/action boundary, the style contract keeps IBM Plex/Nugu-token usage enforced, every QML component and IPC method
40 41 are documented with non-thin inventory rows, QML imports stay local/Qt/Quickshell, every component has an
41 42 early decision/why comment, QML has no unresolved TODO/stub comments, local resources
42 43 are audited, the bundled palette matches

quickshell/nugu/STYLE.md

Added
new file mode 100644
1 +# Nugu Quickshell style contract
3 +This file makes the visual integration rule auditable before live replacement.
4 +It is not human style approval; screenshots and human approval remain required
5 +before Ironbar or Mako retirement.
7 +## Nugu semantic rules
9 +- content.* is for app/content text surfaces.
10 +- ui.* is for chrome, widgets, borders, bars, popups, and status surfaces.
11 +- `error`, `warning`, `info`, and `debug` are semantic signal colors only.
12 +- Active UI uses `ui.focus` as background and `content.backdrop` as foreground.
13 +- Hover/accent UI uses `ui.accent` as background and `content.backdrop` as foreground.
14 +- Muted UI text uses `ui.minor` over `ui.backdrop`.
15 +- Borders and accent lines use `ui.accent` unless a semantic danger/warning state is active.
17 +## Font rules
19 +Only IBM Plex fonts are allowed in QML:
21 +- `IBM Plex Sans` for launcher, popups, notifications, and readable UI text;
22 +- `IBM Plex Mono` for status bar widgets, diagnostics, counters, dates, and clipboard previews.
24 +## Color rules
26 +QML components must consume colors through `Theme.qml` properties. Hard-coded hex
27 +colors are allowed only inside `Theme.qml` as fallback palette values for audit
28 +and smoke resilience. Other QML files may use `transparent` and alpha suffixes on
29 +Nugu tokens such as `` `${theme.ui.backdrop}f2` ``.
31 +## Verification boundary
33 +`audit.sh` enforces the static style contract:
35 +```sh
36 +quickshell/nugu/audit.sh
37 +```
39 +Final visual acceptance still needs dark/light screenshots and human approval for
40 +same style or better looks. Static style checks cannot complete the goal alone.

quickshell/nugu/audit.sh

Modified
21 21 qml_files = sorted(config_dir.glob("*.qml"))
22 22 code_by_file = {}
23 23 decision_comment_files = set()
24 -required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "audit.sh", "smoke.sh", "live-check.sh")
24 +style_font_refs = 0
25 +style_hex_refs = 0
26 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "audit.sh", "smoke.sh", "live-check.sh")
26 28 for name in required_files:
27 29 if not (config_dir / name).exists():
81 83 readme_path = config_dir / "README.md"
82 84 if readme_path.exists():
83 85 readme_text = readme_path.read_text()
84 - for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "audit.sh", "smoke.sh", "live-check.sh", "qs -c nugu", "qs ipc -c nugu"):
86 + for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "audit.sh", "smoke.sh", "live-check.sh", "qs -c nugu", "qs ipc -c nugu"):
85 87 if marker not in readme_text:
86 88 errors.append(f"README.md missing self-contained entry marker {marker!r}")
87 89 else:
204 206 if 'Quickshell.env("HOME")' in code and rel.as_posix() != "Theme.qml":
205 207 errors.append(f"{rel}: HOME path access belongs in Theme.qml unless explicitly audited")
209 + for match in re.finditer(r'font\.family\s*:\s*"([^"]+)"', code):
210 + style_font_refs += 1
211 + family = match.group(1)
212 + if family not in ("IBM Plex Sans", "IBM Plex Mono"):
213 + errors.append(f"{rel}: non-IBM Plex font family {family!r}")
215 + for match in re.finditer(r'#[0-9A-Fa-f]{6,8}\b', code):
216 + style_hex_refs += 1
217 + if rel.as_posix() != "Theme.qml":
218 + errors.append(f"{rel}: hard-coded hex color {match.group(0)!r}; use Theme.qml Nugu tokens")
220 +style_doc = config_dir / "STYLE.md"
221 +if style_doc.exists():
222 + style_text = style_doc.read_text().lower()
223 + required_style_markers = (
224 + "content.* is for app/content text surfaces",
225 + "ui.* is for chrome",
226 + "ibm plex sans",
227 + "ibm plex mono",
228 + "hard-coded hex",
229 + "theme.qml",
230 + "human approval",
231 + "same style or better looks",
232 + "static style checks cannot complete the goal alone",
234 + for marker in required_style_markers:
235 + if marker not in style_text:
236 + errors.append(f"STYLE.md missing style contract marker {marker!r}")
237 +else:
238 + errors.append("missing STYLE.md")
207 240 palette = config_dir / "nugu.json"
208 241 generated = repo_dir / "hypr" / "generated" / "nugu.json"
209 242 contrast_pairs = []
604 637 print(f"parity_rows={len(parity_rows)}")
605 638 print(f"perf_rows={len(perf_rows)}")
606 639 print("perf_budget=ok")
640 +print(f"style_font_refs={style_font_refs}")
641 +print(f"style_hex_refs={style_hex_refs}")
642 +print("style_contract=ok")
607 643 print("rollout_runbook=ok")
608 644 print(f"hypr_migration_rows={len(hypr_migration_rows)}")
609 645 print(f"hypr_current_refs={len(hypr_current_refs)}")