Files

T

darmanandClaude Opus 5 b16cc93ff6 refactor(quickshell): move every color and font into a Theme singleton

The shell was running two unrelated palettes: an amber one (#FFD063 accent,
#EEEEEE text, #0F1012 panels) hardcoded as ~200 raw hex literals across the
launchers, sidebar, systray, vitals and notifications, and an orange one
(#e8722a) that only the dense bar had, tokenized as per-file properties.

This unifies on the ORANGE values under the AMBER naming scheme, and moves the
lot into widgets/theme/Theme.qml. `surface` takes the dense bar's void
(#0a0a0a) rather than the old panel background. Zero color and font literals
remain anywhere under widgets/ outside Theme.qml.

Collisions resolved, all near-duplicates that wanted to be one token:
  - #0F1012 + #0A0A0C + #0a0a0a -> surface
  - #EEEEEE + #dedede           -> text
  - #7A7B7D + #858585           -> muted
  - #292C30 + #22262C           -> raised
  - #FFD063 + #e8722a           -> accent

Two derived things rather than literals. accentSoft (the pale flash the
top/bottom bars show while a launcher is open) was a hand-picked #FFF3C0
against amber, which is simply wrong against orange; it is now
Qt.tint(accent, white 55%), a ratio checked against the original (amber tinted
55% gives #FFE9B8 vs the hand-picked #FFF3C0). And the dense bar had been
hand-encoding Qt.rgba(0.87,0.87,0.87,a) and Qt.rgba(0.91,0.45,0.16,a), which
are just text and accent at alpha -- now textAlpha(a)/accentAlpha(a), so they
track a palette change instead of silently drifting.

Fonts came along too. Digital-7 Mono is dropped for DepartureMono: it was
never packaged, relying on a manual ~/.dots/fonts/digital_7 install that does
not exist on terra, so `fc-match "Digital-7 Mono"` resolved to DejaVu Sans and
all 38 of those sites -- the launcher lists, sidebar clock, systray labels,
every vitals readout -- were silently rendering in a PROPORTIONAL fallback.
Numeric columns should visibly improve. readoutFont is an alias of displayFont
rather than a second literal so the two roles cannot drift apart.

quickshell/CLAUDE.md updated: it said "No shared theme/tokens file yet" and
told contributors to grep for the existing hex color, which would now
reintroduce exactly what this removes.

Verified: no file references Theme. without the import, none imports it
unused, and the whole shell -- launchers, sidebar, vitals, systray,
notifications, not just the harness -- hot-reloaded clean on terra.
tests/HeadlessSmoke.qml deliberately keeps its own copies; its value is having
no dependencies.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SgcWkm3t6BDQktYHQvb8Hx

2026-08-28 07:56:25 +02:00

4.3 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A Quickshell configuration — a QML-based Wayland desktop shell (bar, launcher, tray, decorations) for a Hyprland/wlroots setup. ~/.config/quickshell is a symlink to this repo, so Quickshell loads shell.qml here as the "default" config.

Running / testing changes

qs                 # runs ~/.config/quickshell/shell.qml (this repo, since it's the symlinked default config)
qs -p .            # run this directory explicitly regardless of symlink
qs -n              # exit immediately if another instance is already running (use to avoid duplicate shells while iterating)

Quickshell hot-reloads QML on file save when already running, so for most edits just save and check the running instance rather than restarting qs. There is no separate build/lint/test tooling in this repo — verification is visual/behavioral via the running shell. qmlls (QML language server) is configured via .qmlls.ini for editor diagnostics.

Architecture

shell.qml is the entry point: a Scope that instantiates the top-level pieces — Bar, BarBottom, BarTop, and a hidden Launcher — as siblings. Each top-level widget manages its own PanelWindow(s); there's no central layout manager.

Import convention: QML modules are imported by their path under the repo root using the qs. namespace, e.g. import qs.widgets.launcher, import qs.widgets.decoration. Sibling files in the same directory are imported with a relative string import instead (e.g. Bar.qml does import "modules").

Multi-monitor: Bar/BarTop/BarBottom each wrap their PanelWindow in Variants { model: Quickshell.screens }, so one window instance is created per connected screen. pragma ComponentBehavior: Bound + required property var modelData is the standard pattern for these per-screen delegates.

Directory layout:

widgets/bar/ — Bar.qml is the main sidebar (right-anchored, full height) hosting the module stack (date, clock, tray, decorative dividers); BarTop.qml/BarBottom.qml are thin accent-colored strips anchored to the top/bottom edges.
widgets/bar/modules/ — individual bar widgets (Clock, Date, Tray/TrayItem, Volume) built on the shared BarWidget base component.
widgets/launcher/ — app launcher panel (Launcher → LauncherPanel → SearchBar/TextField), currently a WIP skeleton (search box has no backing logic yet, Launcher.qml is instantiated with visible: false).
widgets/decoration/ — reusable QtQuick Shape-based visual accents (angled panel edges, slashes) used to give bar panels their non-rectangular look. Dummy.qml is a placeholder/test rectangle.
widgets/input/ — thin wrappers around QtQuick.Controls inputs (currently just TextField).
widgets/layout/ — HorizontalStack/VerticalStack: RowLayout/ColumnLayout wrappers that expose default property alias content for terser call sites, with a trailing filler Item that soaks up remaining space.
assets/ — SVG icons referenced via file://${Quickshell.shellDir}/assets/....

Styling: All colors and font families come from the Theme singleton (widgets/theme/Theme.qml, import qs.widgets.theme) — there are no color or font literals left anywhere under widgets/. Add a token there rather than hardcoding a value; alpha variants of the two main colors go through Theme.textAlpha(a) / Theme.accentAlpha(a) instead of a hand-written Qt.rgba(...). Metrics (sizes, spacing) are still per-component.

Component base pattern: BarWidget.qml (widgets/bar/modules/BarWidget.qml) is a WrapperMouseArea + WrapperRectangle combo providing hover-triggered border highlight (Behavior on border.color animation) and Layout.fillWidth. Bar modules extend it via default property alias content rather than duplicating the hover/border chrome.

Fonts: Two families, both via Theme. Theme.displayFont / Theme.readoutFont (an alias of it) are DepartureMono Nerd Font, installed by services/desktop/desktop-apps.nix; Theme.microFont is DejaVu Sans Mono. The shell no longer uses Digital-7 Mono, which was never packaged and depended on a manual ~/.dots/fonts/digital_7 install.

4.3 KiB Raw Blame History

CLAUDE.md

What this is

Running / testing changes

Architecture

4.3 KiB

Raw Blame History