1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
# Unified Desktop Theme, Design
Date: 2026-09-11
Status: approved, phase 1 not yet implemented
## Goal
One consistent visual identity across the desktop: Catppuccin Macchiato as the
fixed base, Noto Sans as the UI font, Inconsolata Nerd Font Mono as the
monospace font. The accent color follows the wallpaper through pywal, but is
always snapped to a real Macchiato accent so the result is never unreadable.
Phase 1 covers rofi only. Later phases extend the same mechanism to waybar,
dunst, kitty, conky, hyprland and quickshell.
## Problem
The rofi setup has grown five independent theme systems with three different
color sources and three different fonts:
| Theme system | Color source | Used by |
| --- | --- | --- |
| `darknix/` | pywal (`~/.cache/wal/darknix-colors.rasi`) | appsmenu, emoji, notes, qemu, scrotmenu |
| `launchers/type-2/style-1` (adi1090x) | `colors/catppuccin.rasi` | sshmenu, github-repos, hypr-windows, cliphist |
| `launchers/type-1` (adi1090x) | `colors/catppuccin.rasi` | ALT+F2 launcher |
| `powermenu/type-4` (adi1090x) | `colors/catppuccin.rasi` | Mod+x powermenu |
| `elegantVagrant/` | self-contained | rofipass |
| (none) | rofi defaults | ddgr_search.py |
Fonts in play: `JetBrains Mono Nerd Font 10` (adi1090x shared/fonts.rasi),
`Mono 12` (rofi config.rasi), plus whatever each standalone theme sets. Neither
matches the Qt/GTK setting, which is already Noto Sans + Inconsolata Nerd Font
Mono.
The `colors/catppuccin.rasi` shipped by adi1090x is not Macchiato. Its
background is `#1E1D2F` and its `selected` is `#7AA2F7`, a Tokyo Night blue.
## Decisions
Four decisions were made during brainstorming, each with alternatives
considered:
1. **Color model: Macchiato base with a pywal-driven accent.** Structural
colors (backgrounds, text) are fixed Macchiato. Exactly one color, the
accent, follows the wallpaper. Rejected: fully fixed palette (loses the
wallpaper tie-in, and the pywal pipeline already exists); fully
pywal-driven (readability not guaranteed).
2. **Accent selection: snap to the nearest Macchiato accent.** pywal's dominant
color is matched by hue against the 14 named Macchiato accents and the
closest one wins. Rejected: raw pywal color (can be muddy or dark against
the base); raw color with a contrast floor (keeps more wallpaper fidelity
but can emit colors outside the palette).
3. **Scope: rofi only in phase 1.** Rofi holds the actual inconsistency and
exercises every part of the pipeline. Once proven, each further app is a
single template file.
4. **Layouts: three shapes, one palette.** The scripts genuinely have three
different jobs and forcing one shape on all of them would push the variation
back into scattered `-theme-str` strings. Revisit if three proves wrong.
## Architecture
```
~/.config/wal/templates/udt-accent.rasi # pywal template, emits raw dominant color
~/.config/rofi/udt/
palette.rasi # Macchiato, fixed, hand-written
accent.rasi # symlink -> ~/.cache/wal/udt-accent.rasi (generated)
common.rasi # fonts, radii, spacing, element states; imports palette + accent
launcher.rasi # grid + search
menu.rasi # small, fixed options
list.rasi # tall searchable list
~/bin/udt-accent # snaps pywal dominant color to nearest Macchiato accent
```
Data flow on wallpaper change:
1. pywal renders `udt-accent.rasi` into `~/.cache/wal/` with the raw dominant
color.
2. `udt-accent` reads it, snaps to the nearest Macchiato accent, rewrites the
file in place.
3. Next rofi invocation picks it up. Rofi reads its theme per launch, so no
daemon and no reload are needed.
Step 3 is why this needs no running process. `udt-accent` is called from
`wal.sh`, which already performs the symlink-and-restart sequence for dunst and
kitty.
## Color contract
`palette.rasi` defines the full Macchiato palette by semantic name. Values are
from the official `catppuccin/palette` repository:
```
base #24273a mantle #1e2030 crust #181926
text #cad3f5 subtext1 #b8c0e0 subtext0 #a5adcb
overlay2 #939ab7 overlay1 #8087a2 overlay0 #6e738d
surface2 #5b6078 surface1 #494d64 surface0 #363a4f
rosewater #f4dbd6 flamingo #f0c6c6 pink #f5bde6 mauve #c6a0f6
red #ed8796 maroon #ee99a0 peach #f5a97f yellow #eed49f
green #a6da95 teal #8bd5ca sky #91d7e3 sapphire #7dc4e4
blue #8aadf4 lavender #b7bdf8
```
`accent.rasi` defines exactly one variable, `@accent`, always equal to one of
the 14 accent colors above.
Themes reference semantic names only, never literal hex. Everything structural
is fixed; only `@accent` moves.
## The accent snapper
`~/bin/udt-accent`, Python 3, standard library only (`colorsys`, `re`).
- Reads the raw color from `~/.cache/wal/udt-accent.rasi`.
- Converts it and the 14 candidate accents to HLS.
- Picks the candidate with the smallest circular hue distance.
- Writes `* { accent: #rrggbb; }` back to the same path.
- Falls back to `mauve` when the cache file is missing or unparseable, so a
fresh machine or a failed pywal run still yields a working theme.
Hue alone is the comparison metric: the Macchiato accents are already
normalized for lightness and saturation against the base, so matching hue is
what selects the perceptually right one. A near-grey wallpaper color has an
unstable hue, so colors below a small saturation threshold fall back to `mauve`
rather than snapping arbitrarily.
Leaves one runnable self-check (`udt-accent --selftest`) asserting that a known
orange input snaps to `peach`, a known green to `green`, and a grey to the
`mauve` fallback.
## Layouts
All three import `common.rasi`, which holds the shared identity: Noto Sans for
UI text, Inconsolata Nerd Font Mono for monospace fields, one border radius,
one border width, and one `element.selected` treatment (accent background,
`@base` text).
- **`launcher.rasi`**: centered, search bar, icon grid. App launching.
- **`menu.rasi`**: small centered box, no search, few fixed options.
- **`list.rasi`**: tall, search bar, single wide column. Long searchable lists.
## Migration
Eleven targets. Each gets its `-theme` argument pointed at one of the three new
files; `ddgr_search.py` has no `-theme` today and gains one.
| Layout | Targets |
| --- | --- |
| `launcher.rasi` | `blackpearl-appsmenu.sh`, `launchers/type-1/launcher.sh` (ALT+F2) |
| `menu.rasi` | `qar-scrotmenu.sh`, `blackpearl-notes.sh`, `powermenu/type-4/powermenu.sh` (Mod+x) |
| `list.rasi` | `blackpearl-sshmenu.sh`, `blackpearl-emoji.sh`, `rofi-qemu.sh`, `github-repos.sh`, `hypr-windows.sh`, `rofipass`, `ddgr_search.py`, cliphist bind |
The cliphist binding carries its `-theme` inline in
`~/.config/hypr/sections/keybindings.lua` rather than in a script, so that line
is edited directly.
`launchers/type-1` and `powermenu/type-4` are third-party adi1090x scripts.
They are treated like any other target, a `-theme` path change only, with no
attempt to restructure them.
The old theme directories (`darknix/`, `elegantVagrant/`, `launchers/`,
`applets/`, `powermenu/`) stay on disk untouched. Deleting them is a separate
decision to be made after the new themes are confirmed good.
Out of scope: `ronema` (rofi NetworkManager applet, no longer used, pending
archival by the user).
## Verification
Visual, performed by the user. Each of the eleven targets is launched and
eyeballed against three checks: colors are Macchiato, fonts are Noto Sans and
Inconsolata, and the shape suits the job.
The accent pipeline is verified separately by changing the wallpaper to images
with clearly different dominant hues and confirming the accent tracks and stays
readable.
`udt-accent --selftest` covers the snapping logic non-visually.
## Later phases
Each subsequent app reuses `palette.rasi` and `accent.rasi` through a
format-appropriate template, and needs no new mechanism:
- **waybar**: CSS, consumes a generated `colors.css`.
- **dunst**: already pywal-templated, template gets repointed.
- **kitty**: already pywal-templated, same.
- **conky**: Lua config, reads generated values.
- **hyprland**: window borders use the accent.
- **quickshell**: new work, to be designed when the user starts on it.
## License
GPLv2 (to be confirmed). Needs `LICENSE`, per-file header notices with
`Copyright (C) 2026 Danilo M. <danix@danix.xyz>`, and a License section in the
README, added early rather than retrofitted. The README also needs the standard
Development Approach section disclosing AI-assisted development.
|
