Add custom ArchLogo cursor theme (Hyprcursor + XCursor), document it

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dujsk9jYfxUVLtb5B8eC94
This commit is contained in:
nico
2026-09-19 22:30:57 +02:00
parent 2b612d6e63
commit 3508e70b93
6 changed files with 383 additions and 1 deletions

View File

@@ -13,6 +13,7 @@ My personal dotfiles for a [Hyprland](https://hyprland.org/) desktop on Arch Lin
| Bar | Custom [Quickshell](https://quickshell.org/) shell (`quickshell/default/`) — replaces Waybar entirely |
| Launcher | Rofi |
| Terminal | Kitty |
| Cursor | Custom Arch-logo cursor set (pointer, text, resize, wait spinner, …) in the rice palette — artwork in [`shapes.py`](hypr/cursor/shapes.py), [`build.py`](hypr/cursor/build.py) installs a Hyprcursor and an XCursor theme to `~/.local/share/icons/ArchLogo` |
| Notifications | [mako](mako/) — themed via aether, same as the rest |
| Theming | [aether](aether/) — palette-driven theme generator |
| Qt/GTK theming | qt5ct, qt6ct, nwg-look |
@@ -37,6 +38,16 @@ All the stats are pulled by small shell scripts in `quickshell/default/scripts/`
Hyprland itself is configured via [`hypr/hyprland.lua`](hypr/hyprland.lua) (Hyprland's Lua config API) — that's the active config; `hyprland.conf` is kept around for reference but is no longer loaded. One consequence: `hyprctl dispatch` (and anything sending it a raw dispatch string, like this bar's workspace/window-switcher clicks) needs the new `hl.dsp.*` Lua-expression syntax instead of the classic one, e.g. `hl.dsp.focus({workspace = 1})` rather than `workspace 1`.
## Cursor
The mouse cursor is a custom theme, `ArchLogo`, with every shape redrawn in the rice style instead of only the arrow:
- **Default pointer** — the Arch logo, rotated like a classic arrow, plain accent blue without an outline. Copy / context-menu / alias / help / no-drop are the same arrow with a small badge, and the link pointer is the logo upright
- **Everything else** — text I-beam, resize arrows (edges, corners, column/row, all-direction), crosshair, cell, grab/grabbing hand, zoom, X, and a red not-allowed sign. These have a dark outline plus a light rim so they stay visible on blue or dark backgrounds
- **Animated** — `wait` is a spinning ring, `progress` is the arrow with a small spinner badge
The artwork is drawn procedurally in [`hypr/cursor/shapes.py`](hypr/cursor/shapes.py); [`hypr/cursor/build.py`](hypr/cursor/build.py) renders it (needs `rsvg-convert` and `hyprcursor-util`) into a Hyprcursor theme for Hyprland and an XCursor theme for GTK/Qt/XWayland apps, both installed to `~/.local/share/icons/ArchLogo`. Adwaita is only used as the shape/alias list and fallback. After editing `shapes.py`, run `python3 hypr/cursor/build.py` and `hyprctl setcursor ArchLogo 24`. `hyprland.lua` sets the theme via `XCURSOR_THEME` / `HYPRCURSOR_THEME` and gsettings.
## Theming (aether)
The color palette lives in [`aether/`](aether/) and is the single source of truth — [`aether/theme/colors.toml`](aether/theme/colors.toml) defines the palette, and aether renders it out into per-app configs (Hyprland, Kitty, Rofi, Waybar-era CSS, btop, Zed, etc.), most of which get `@import`ed or sourced by that app's real config rather than edited directly. The bar's own colors in `Bar.qml` are hand-matched to this palette rather than generated, since Quickshell reads QML, not CSS.
@@ -117,7 +128,7 @@ Beyond Hyprland itself, the bar's scripts expect: `quickshell`, `nmcli`, `wpctl`
## Layout
```
hypr/ Hyprland config (hyprland.lua is active, .conf kept for reference) + wallpaper.png
hypr/ Hyprland config (hyprland.lua is active, .conf kept for reference) + wallpaper.png + cursor/ (cursor theme source)
quickshell/ The bar (Bar.qml + helper QML components + scripts/)
rofi/ Launcher config + theme
kitty/ Terminal config + theme

Binary file not shown.

Binary file not shown.

177
hypr/cursor/build.py Normal file
View File

@@ -0,0 +1,177 @@
#!/usr/bin/env python3
"""Build the "ArchLogo" cursor theme: every Adwaita cursor shape redrawn in the
rice style (artwork in shapes.py: Arch-logo pointer, blue + dark outline).
Produces both formats into ~/.local/share/icons/ArchLogo:
- hyprcursor (compiled with hyprcursor-util) for Hyprland itself
- XCursor (written directly, no xcursorgen needed) for GTK/Qt/XWayland apps
Adwaita is only used as the shape list / alias map and as the fallback theme.
Needs: rsvg-convert, hyprcursor-util, and Adwaita cursors in /usr/share/icons.
"""
import os
import re
import shutil
import struct
import subprocess
import sys
import tempfile
import zlib
HERE = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, HERE)
from shapes import SHAPES, DELAY_MS # noqa: E402
BASE = "/usr/share/icons/Adwaita"
NAME = "ArchLogo"
DEST = os.path.expanduser(f"~/.local/share/icons/{NAME}")
DESC = "Arch-logo cursor set in the rice palette"
# Same sizes Adwaita's hyprcursor extraction uses, plus a few X11 favourites.
HYPR_SIZES = [24, 30, 36, 48, 72, 96]
XCURSOR_SIZES = [24, 30, 32, 36, 48, 64, 72, 96]
_cache = {}
def render(svg, size):
"""SVG string -> (w, h, rows of RGBA bytes), cached (hypr and X sizes overlap)."""
key = (svg, size)
if key not in _cache:
png = subprocess.run(["rsvg-convert", "-f", "png", "-w", str(size), "-h", str(size)],
input=svg.encode(), capture_output=True, check=True).stdout
_cache[key] = (png, read_png(png))
return _cache[key]
def read_png(d):
"""Minimal decoder for the 8-bit RGBA non-interlaced PNGs rsvg-convert writes."""
p, idat = 8, b""
while p < len(d):
ln, typ = struct.unpack(">I4s", d[p:p + 8])
body = d[p + 8:p + 8 + ln]
p += 12 + ln
if typ == b"IHDR":
w, h, bd, ct, _, _, il = struct.unpack(">IIBBBBB", body)
assert (bd, ct, il) == (8, 6, 0), "expected 8-bit RGBA, non-interlaced"
elif typ == b"IDAT":
idat += body
raw, stride, prev, i, rows = zlib.decompress(idat), w * 4, bytearray(w * 4), 0, []
for _ in range(h):
f, line = raw[i], bytearray(raw[i + 1:i + 1 + stride])
i += 1 + stride
for x in range(stride):
a = line[x - 4] if x >= 4 else 0
b = prev[x]
c = prev[x - 4] if x >= 4 else 0
if f == 1:
line[x] = (line[x] + a) & 255
elif f == 2:
line[x] = (line[x] + b) & 255
elif f == 3:
line[x] = (line[x] + ((a + b) >> 1)) & 255
elif f == 4:
pa, pb, pc = abs(b - c), abs(a - c), abs(a + b - 2 * c)
line[x] = (line[x] + (a if pa <= pb and pa <= pc else (b if pb <= pc else c))) & 255
rows.append(line)
prev = line
return w, h, rows
def xcursor_image(svg, size, hot, delay):
png, (w, h, rows) = render(svg, size)
pix = bytearray()
for r in rows:
for x in range(w):
R, G, B, A = r[x * 4:x * 4 + 4]
# XCursor stores premultiplied ARGB, little-endian
pix += struct.pack("<I", (A << 24) | ((R * A // 255) << 16) | ((G * A // 255) << 8) | (B * A // 255))
xh, yh = round(hot[0] / 256 * size), round(hot[1] / 256 * size)
return struct.pack("<9I", 36, 0xFFFD0002, size, 1, w, h, xh, yh, delay) + bytes(pix), size
def write_xcursor(path, hot, frames):
delay = DELAY_MS if len(frames) > 1 else 0
# a reader picks the best size, then plays every chunk of that size in TOC order
chunks = [xcursor_image(f, s, hot, delay) for s in XCURSOR_SIZES for f in frames]
off = 16 + 12 * len(chunks)
toc, body = b"", b""
for data, size in chunks:
toc += struct.pack("<3I", 0xFFFD0002, size, off + len(body))
body += data
with open(path, "wb") as f:
f.write(struct.pack("<4s3I", b"Xcur", 16, 0x10000, len(chunks)) + toc + body)
def write_hypr_shape(shape_dir, name, hot, frames):
"""Replace one extracted Adwaita shape (PNGs + meta.hl), keeping its define_override aliases."""
meta_path = os.path.join(shape_dir, "meta.hl")
overrides = re.findall(r"^define_override.*$", open(meta_path).read(), re.M)
for f in os.listdir(shape_dir):
if f.endswith(".png"):
os.remove(os.path.join(shape_dir, f))
lines = ["resize_algorithm = none", f"hotspot_x = {hot[0] / 256:.4f}", f"hotspot_y = {hot[1] / 256:.4f}", ""]
n = 0
for f in frames:
for s in HYPR_SIZES:
fn = f"{name}_{n:03d}.png"
open(os.path.join(shape_dir, fn), "wb").write(render(f, s)[0])
lines.append(f"define_size = {s}, {fn}, {DELAY_MS if len(frames) > 1 else 50}")
n += 1
open(meta_path, "w").write("\n".join(lines + [""] + overrides) + "\n")
def main():
for tool in ("rsvg-convert", "hyprcursor-util"):
if not shutil.which(tool):
sys.exit(f"missing dependency: {tool}")
cur_base = os.path.join(BASE, "cursors")
if not os.path.isdir(cur_base):
sys.exit(f"base cursor theme not found: {BASE}")
tmp = tempfile.mkdtemp(prefix="archcursor-")
try:
# --- hyprcursor: extract Adwaita, swap every shape, recompile ---
subprocess.run(["hyprcursor-util", "--extract", BASE, "--output", tmp], check=True, stdout=subprocess.DEVNULL)
src = os.path.join(tmp, "extracted_" + os.path.basename(BASE))
hdir = os.path.join(src, "hyprcursors")
for name in sorted(os.listdir(hdir)):
if name not in SHAPES:
sys.exit(f"no artwork for cursor shape '{name}'")
write_hypr_shape(os.path.join(hdir, name), name, *SHAPES[name])
manifest = os.path.join(src, "manifest.hl")
text = open(manifest).read()
text = re.sub(r"name = .*", f"name = {NAME}", text)
text = re.sub(r"description = .*", f"description = {DESC}", text)
open(manifest, "w").write(text)
out = os.path.join(tmp, "out")
os.makedirs(out)
subprocess.run(["hyprcursor-util", "--create", src, "--output", out], check=True, stdout=subprocess.DEVNULL)
built = [d for d in os.listdir(out) if os.path.exists(os.path.join(out, d, "manifest.hl"))]
if len(built) != 1:
sys.exit(f"unexpected hyprcursor-util output: {os.listdir(out)}")
shutil.rmtree(DEST, ignore_errors=True)
shutil.copytree(os.path.join(out, built[0]), DEST)
# --- XCursor: one file per real shape, Adwaita's alias names symlinked to them ---
cur = os.path.join(DEST, "cursors")
os.makedirs(cur, exist_ok=True)
for n in sorted(os.listdir(cur_base)):
p = os.path.join(cur_base, n)
if os.path.islink(p):
os.symlink(os.path.basename(os.path.realpath(p)), os.path.join(cur, n))
elif n in SHAPES:
write_xcursor(os.path.join(cur, n), *SHAPES[n])
else:
sys.exit(f"no artwork for cursor shape '{n}'")
with open(os.path.join(DEST, "index.theme"), "w") as f:
f.write(f"[Icon Theme]\nName={NAME}\nComment={DESC}\nInherits={os.path.basename(BASE)}\n")
finally:
shutil.rmtree(tmp, ignore_errors=True)
print(f"installed {NAME} -> {DEST}")
if __name__ == "__main__":
main()

187
hypr/cursor/shapes.py Normal file
View File

@@ -0,0 +1,187 @@
"""Cursor artwork for the ArchLogo theme, drawn procedurally as SVG.
Everything lives in a 256x256 box. Style: accent-blue shapes with a dark outline,
the Arch logo as the pointer, red only for "forbidden". SHAPES maps each XCursor
name to (hotspot in that box, [svg frames]); more than one frame = animated.
"""
OUT = "#0b1a26" # outline
BLUE = "#1793d1" # accent (aether color for the rice)
LIGHT = "#e6f1f8"
TRACK = "#2a4a63"
RED = "#e5546b"
ARCH = ("m127.98 12.07c-10.316 25.309-16.543 41.855-28.031 66.41 7.043 7.4609 15.691 16.156 29.734 25.977-15.098-6.207-25.395-12.445-33.094-18.918-14.703 30.68-37.742 74.391-84.492 158.39 36.746-21.219 65.23-34.293 91.773-39.289-1.1406-4.8945-1.7852-10.195-1.7422-15.734l0.042969-1.1719c0.58203-23.551 12.828-41.645 27.336-40.418 14.508 1.2266 25.781 21.316 25.199 44.867-0.10938 4.4219-0.60938 8.6914-1.4805 12.641 26.258 5.1328 54.438 18.18 90.684 39.105-7.1484-13.156-13.527-25.016-19.621-36.316-9.5938-7.4336-19.605-17.117-40.023-27.594 14.035 3.6406 24.082 7.8516 31.914 12.555-61.941-115.32-66.957-130.66-88.199-180.5z")
DEFS = f'<defs><path id="arch" fill-rule="evenodd" d="{ARCH}"/></defs>'
FRAMES = 20
DELAY_MS = 50
def svg(body):
return f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">{DEFS}{body}</svg>'
# --- primitives: F = filled shape, S = stroked line; lay() draws outlines first, then colours ---
def F(markup, color=BLUE):
return ("f", markup, 0, color)
def S(markup, w, color=BLUE):
return ("s", markup, w, color)
HALO = 16 # extra light rim outside the dark outline, so the cursor also reads on blue/dark backgrounds
def lay(items, ow=18):
halo, dark, top = [], [], []
for kind, m, w, c in items:
if kind == "f":
halo.append(f'<g fill="{LIGHT}" stroke="{LIGHT}" stroke-width="{ow + HALO}" stroke-linejoin="round">{m}</g>')
dark.append(f'<g fill="{OUT}" stroke="{OUT}" stroke-width="{ow}" stroke-linejoin="round">{m}</g>')
top.append(f'<g fill="{c}">{m}</g>')
else:
cap = 'stroke-linecap="round" stroke-linejoin="round"'
halo.append(f'<g fill="none" stroke="{LIGHT}" stroke-width="{w + ow + HALO}" {cap}>{m}</g>')
dark.append(f'<g fill="none" stroke="{OUT}" stroke-width="{w + ow}" {cap}>{m}</g>')
top.append(f'<g fill="none" stroke="{c}" stroke-width="{w}" {cap}>{m}</g>')
return "".join(halo + dark + top)
def poly(pts):
return f'<polygon points="{" ".join(f"{x},{y}" for x, y in pts)}"/>'
def line(x1, y1, x2, y2):
return f'<path d="M{x1} {y1}L{x2} {y2}"/>'
def rot(body, deg):
return f'<g transform="rotate({deg} 128 128)">{body}</g>'
def glyph(d, w, color=OUT):
return f'<path d="{d}" fill="none" stroke="{color}" stroke-width="{w}" stroke-linecap="round" stroke-linejoin="round"/>'
# --- pointers -------------------------------------------------------------------------------
def arrow(scale=1.0, outline=True):
if not outline:
return f'<g transform="translate(14 14) rotate(-26.565) scale(0.88) translate(-127.98 -12.07)"><use href="#arch" fill="{BLUE}"/></g>'
g = ('<g transform="translate(14 14) rotate(-26.565) scale(0.88) translate(-127.98 -12.07)">'
f'<use href="#arch" fill="{LIGHT}" stroke="{LIGHT}" stroke-width="{(18 + HALO) / 0.88:.1f}" stroke-linejoin="round"/>'
f'<use href="#arch" fill="{OUT}" stroke="{OUT}" stroke-width="{18 / 0.88:.1f}" stroke-linejoin="round"/>'
f'<use href="#arch" fill="{BLUE}"/></g>')
if scale != 1.0:
g = f'<g transform="translate(14 14) scale({scale}) translate(-14 -14)">{g}</g>'
return g
def badge(items):
return lay(items)
BX, BY = 194, 194 # badge centre next to the small arrow
def badged(inner):
return svg(arrow(0.72) + inner)
def light_badge(glyphs):
return lay([F(f'<circle cx="{BX}" cy="{BY}" r="44"/>', LIGHT)]) + glyphs
UPRIGHT = ('<g transform="translate(128 30) scale(0.8) translate(-127.98 -12.07)">'
f'<use href="#arch" fill="{LIGHT}" stroke="{LIGHT}" stroke-width="{(18 + HALO) / 0.8:.1f}" stroke-linejoin="round"/>'
f'<use href="#arch" fill="{OUT}" stroke="{OUT}" stroke-width="{18 / 0.8:.1f}" stroke-linejoin="round"/>'
f'<use href="#arch" fill="{BLUE}"/></g>')
# --- resize family --------------------------------------------------------------------------
DOUBLE = poly([(24, 128), (80, 80), (80, 112), (176, 112), (176, 80), (232, 128),
(176, 176), (176, 144), (80, 144), (80, 176)])
COL = (poly([(24, 128), (72, 84), (72, 112), (104, 112), (104, 144), (72, 144), (72, 172)])
+ poly([(232, 128), (184, 84), (184, 112), (152, 112), (152, 144), (184, 144), (184, 172)]))
QUAD = poly([(128, 24), (172, 68), (144, 68), (144, 112), (188, 112), (188, 84), (232, 128),
(188, 172), (188, 144), (144, 144), (144, 188), (172, 188), (128, 232),
(84, 188), (112, 188), (112, 144), (68, 144), (68, 172), (24, 128),
(68, 84), (68, 112), (112, 112), (112, 68), (84, 68)])
IBEAM = [S(line(128, 56, 128, 200), 18), S(line(92, 56, 164, 56), 18), S(line(92, 200, 164, 200), 18)]
PLUS_FAT = poly([(104, 40), (152, 40), (152, 104), (216, 104), (216, 152), (152, 152),
(152, 216), (104, 216), (104, 152), (40, 152), (40, 104), (104, 104)])
def hand(fingers, thumb=True):
parts = [F('<rect x="72" y="120" width="112" height="88" rx="28"/>')]
for x, y in fingers:
parts.append(F(f'<rect x="{x}" y="{y}" width="24" height="{150 - y}" rx="12"/>'))
if thumb:
parts.append(F('<rect x="44" y="128" width="34" height="52" rx="17" transform="rotate(-28 60 154)"/>'))
return svg(lay(parts))
def ring(angle_deg=0, cx=128, cy=128, r=84, w=28, scale=1.0):
d = f"M{cx} {cy - r} A{r} {r} 0 1 1 {cx - r} {cy}"
track = f'<circle cx="{cx}" cy="{cy}" r="{r}"/>'
arc = f'<g transform="rotate({angle_deg} {cx} {cy})"><path d="{d}"/></g>'
return lay([S(track, w, TRACK), S(arc, w)])
def build():
one = lambda hot, body: (hot, [svg(body)])
c = (128, 128)
a = (14, 14)
forbidden = lay([S('<circle cx="128" cy="128" r="88"/>', 26, RED), S(line(66, 66, 190, 190), 26, RED)])
zoom = lambda plus: svg(lay([S('<circle cx="108" cy="108" r="64"/>', 20), S(line(156, 156, 224, 224), 30)]
+ [S(line(78, 108, 138, 108), 14, LIGHT)]
+ ([S(line(108, 78, 108, 138), 14, LIGHT)] if plus else [])))
shapes = {
"default": one(a, arrow(outline=False)),
"context-menu": one(a, badged(light_badge(
glyph("M172 180H216M172 196H216M172 212H216", 9)))),
"copy": one(a, badged(light_badge(glyph("M194 170V218M170 194H218", 12)))),
"alias": one(a, badged(light_badge(
glyph("M172 216C172 190 186 182 208 182", 11)
+ f'<polygon points="222,182 202,166 202,198" fill="{OUT}"/>'))),
"no-drop": one(a, badged(lay([S(f'<circle cx="{BX}" cy="{BY}" r="34"/>', 14, RED),
S(line(BX - 24, BY - 24, BX + 24, BY + 24), 14, RED)], 10))),
"help": one(a, badged(light_badge(
glyph("M176 182C176 166 210 164 212 182C214 198 196 198 196 210", 11)
+ f'<circle cx="196" cy="226" r="6.5" fill="{OUT}"/>'))),
"not-allowed": one(c, forbidden),
"pointer": one((128, 30), UPRIGHT),
"text": one(c, lay(IBEAM)),
"vertical-text": one(c, rot(lay(IBEAM), 90)),
"crosshair": one(c, lay([S(line(128, 26, 128, 104), 16), S(line(128, 152, 128, 230), 16),
S(line(26, 128, 104, 128), 16), S(line(152, 128, 230, 128), 16),
F('<circle cx="128" cy="128" r="10"/>')])),
"cell": one(c, lay([F(PLUS_FAT)])),
"X_cursor": one(c, lay([S(line(52, 52, 204, 204), 28), S(line(204, 52, 52, 204), 28)])),
"ew-resize": one(c, lay([F(DOUBLE)])),
"ns-resize": one(c, rot(lay([F(DOUBLE)]), 90)),
"nesw-resize": one(c, rot(lay([F(DOUBLE)]), -45)),
"nwse-resize": one(c, rot(lay([F(DOUBLE)]), 45)),
"col-resize": one(c, lay([F(COL), S(line(128, 60, 128, 196), 16)])),
"row-resize": one(c, rot(lay([F(COL), S(line(128, 60, 128, 196), 16)]), 90)),
"all-resize": one(c, lay([F(QUAD)])),
"all-scroll": one(c, lay([F(QUAD)])),
"grab": one((128, 104), hand([(76, 76), (104, 52), (132, 60), (160, 84)])),
"grabbing": one(c, hand([(76, 104), (104, 100), (132, 102), (160, 108)])),
"zoom-in": one((108, 108), zoom(True)),
"zoom-out": one((108, 108), zoom(False)),
"wait": (c, [svg(ring(i * 360 / FRAMES)) for i in range(FRAMES)]),
"progress": (a, [svg(arrow(0.72) + ring(i * 360 / FRAMES, BX, BY, 30, 14)) for i in range(FRAMES)]),
}
# single-ended resize cursors (the window-edge ones) reuse the double-headed arrows
for name, src in {"e-resize": "ew-resize", "w-resize": "ew-resize", "n-resize": "ns-resize",
"s-resize": "ns-resize", "ne-resize": "nesw-resize", "sw-resize": "nesw-resize",
"nw-resize": "nwse-resize", "se-resize": "nwse-resize"}.items():
shapes[name] = shapes[src]
return shapes
SHAPES = build()

View File

@@ -57,6 +57,11 @@ hl.env("XCURSOR_SIZE", 24)
hl.env("HYPRCURSOR_SIZE", 24)
-- Arch-logo pointer, built by hypr/cursor/build.py into ~/.local/share/icons/ArchLogo
hl.env("XCURSOR_THEME", "ArchLogo")
hl.env("HYPRCURSOR_THEME", "ArchLogo")
hl.env("QT_QPA_PLATFORM", "wayland;xcb")
hl.env("GDK_BACKEND", "wayland,x11")
@@ -605,4 +610,6 @@ end)
hl.on("config.reloaded", function()
hl.exec_cmd("gsettings set org.gnome.desktop.interface gtk-theme \"Materia-dark\"")
hl.exec_cmd("gsettings set org.gnome.desktop.interface color-scheme \"prefer-dark\"")
hl.exec_cmd("gsettings set org.gnome.desktop.interface cursor-theme \"ArchLogo\"")
hl.exec_cmd("gsettings set org.gnome.desktop.interface cursor-size 24")
end)