Quickshell Modules

When to Use

Use when building, fixing, or debugging any quickshell module, panel, or popup in ~/dotfiles/.config/quickshell — especially when the bar disappears, IPC targets go missing, a new window misbehaves, or redesigning UI (ControlCenter, DriveHealth, panels). EVERY module goes through the Design-first workflow below by default, new or redesigned, with no need for the user to ask: use every design skill available, make 3-5 HTML/CSS options, open them all with xdg-open in the default browser, user picks, then port to QML. The ONLY ways to skip it: the user says to skip design (e.g. "no design phase", "just port it", "skip html"), or the change has no visual effect (bug fix, logic-only change). Ported UI follows the Bento design language (step 8) with colors ONLY from the system theme, and the layout rules in steps 22-28 and the state rules in steps 36-39. Bug fixes and logic-only changes with no visual change skip the design phase. Never skip it silently: if you skip because the user asked, say so in one line.

Scope note — global web forbiddens vs Bento (read this first)

The frontend-design global forbidden rules (black-white-first, no gradients/glass/chips/uppercase-labels) apply to web/app/marketing UI — they do NOT override the Bento house style inside ~/dotfiles rice. For quickshell modules, 0.3–0.5 alpha glass fills, 22–26px chips, uppercase labels with 1.2–1.3 letter-spacing, and gradient/slider fills are required, not banned. Apply the global bans only when building non-rice UI.

Exploration is the exception: during the Design-first workflow, use the frontend-design skill and the design skills freely. Options may break Bento tokens (radii, label style, chip shapes) because the point is to see different directions. The Bento tokens apply again at port time, unless the user picks a design that deviates (see Design-first step 6).

Color rule (applies to every phase)

SYSTEM THEME ALWAYS. Every color comes from the Matugen-driven colors object in QML, and from the copied colors.css variables in HTML options. No hex literals, no Qt.rgba literals, no hardcoded fallback colors, anywhere. Whatever hue the wallpaper produces is correct: the palette is amber today and may be teal tomorrow. Design by ROLE (primary, secondary, tertiary, surface, surfaceVariant, outline, foreground, background, error), never by hue.

Always on: Matugen + shared glass + two accents

These three apply to every module, option, and port, with no exceptions and no "just this once":

• Matugen always. Every color is a colors.* role (QML) or var(--role) (HTML options). See the Color rule above.
• Glass always, in the shared format. All plugins use ONE glass format. Do not invent a variant. Before writing any surface, find it: read a finished sibling module (and rg -n 'glass|alpha\(colors\.surface|qs-' ~/dotfiles/.config/quickshell plus the matching layerrules in looknfeel.conf) and copy its transparent window, surface alpha, border, radius, and qs-* namespace verbatim. If a shared glass component or helper exists, import and use it instead of re-drawing the rectangle. Step 14 is the baseline recipe; the shared format found in the sibling wins if they differ. If you cannot find the shared format, stop and ask for the file instead of guessing.
• At least two Matugen accent roles, every time. Each module uses two or more DIFFERENT accent roles from primary, secondary, tertiary (error is reserved for errors and does not count). Assign them by purpose (primary = brand and interactive, secondary = complementary or secondary actions, tertiary = data, network, progress), never decoratively. Neutrals (foreground, background, surface, surfaceVariant, outline) do not count as accents. A one-accent module is a defect. Options in the HTML phase follow the same rule with var(--primary) plus at least one of --secondary / --tertiary.