docs: design for DankMaterialShell (niri) profile
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN
This commit is contained in:
@@ -0,0 +1,234 @@
|
|||||||
|
# DankMaterialShell (niri) Profile — Design
|
||||||
|
|
||||||
|
**Date:** 2026-07-24
|
||||||
|
**Branch:** `feat/dank-material-shell`
|
||||||
|
**Status:** Approved (brainstorming)
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Add a `my.profiles.dank` NixOS profile that provides a complete
|
||||||
|
[DankMaterialShell](https://danklinux.com) (DMS) desktop running on the
|
||||||
|
**niri** Wayland compositor, selectable at the SDDM login screen **alongside**
|
||||||
|
the existing KDE session on **mibook** (user `finn`).
|
||||||
|
|
||||||
|
DMS's keybind, spawn, and declarative-settings integration is delivered only
|
||||||
|
through home-manager modules, so this work also introduces home-manager into the
|
||||||
|
flake — as its own opt-in profile (`my.profiles.home-manager`) that the `dank`
|
||||||
|
profile enables as a dependency. Everything stays declarative inside the flake;
|
||||||
|
there is no separate home-manager entrypoint.
|
||||||
|
|
||||||
|
## Background / Research
|
||||||
|
|
||||||
|
DMS is a Quickshell-based Wayland desktop **shell** (bar, launcher, control
|
||||||
|
center, lock screen, notifications) — not a compositor. Its repository
|
||||||
|
(`github:AvengeMedia/DankMaterialShell`) ships a flake with:
|
||||||
|
|
||||||
|
- `nixosModules.dank-material-shell` — system side: installs the `dms-shell`
|
||||||
|
package + `quickshell`, a `dms` systemd **user** service, `dgop` (system
|
||||||
|
monitoring), matugen (dynamic theming), and enables polkit /
|
||||||
|
power-profiles-daemon / accounts-daemon / geoclue2. Configured via
|
||||||
|
`programs.dank-material-shell.*`.
|
||||||
|
- `homeModules.dank-material-shell` — home side: declarative
|
||||||
|
`~/.config/DankMaterialShell/settings.json`, the `dms` user service, plugin
|
||||||
|
management, and the `programs.quickshell` HM program.
|
||||||
|
- `homeModules.niri` — niri-specific integration: generates niri keybinds wired
|
||||||
|
to `dms ipc` (launcher, clipboard, notifications, media/brightness keys, power
|
||||||
|
menu, lock) and `spawn-at-startup` for `dms run`.
|
||||||
|
|
||||||
|
`homeModules.niri` builds on **niri-flake**'s home-manager API
|
||||||
|
(`programs.niri.settings`, `config.lib.niri.actions`); DMS does **not** bundle
|
||||||
|
niri-flake, so it must be added as its own input. quickshell ≥ 0.3.0 is
|
||||||
|
recommended and is available in nixos-unstable → use `pkgs.unstable.quickshell`.
|
||||||
|
|
||||||
|
### Key repo facts
|
||||||
|
|
||||||
|
- This repo is flake-parts based, pins `nixpkgs/nixos-26.05`, and exposes
|
||||||
|
`pkgs.unstable` via an overlay in `machines/configuration.nix`.
|
||||||
|
- `inputs` and `self` are already threaded into every NixOS module via
|
||||||
|
`_module.args` (set in `machines/configuration.nix`), so `modules/` files may
|
||||||
|
take `inputs` / `self` as arguments and `imports = [ inputs.<x>... ]`.
|
||||||
|
- The repo currently uses **no home-manager**; compositor profiles (e.g.
|
||||||
|
`hyprland`) install packages via `users.users.finn.packages`.
|
||||||
|
- mibook currently runs the KDE desktop (`my.profiles.kde-desktop`).
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- **In:** mibook only; niri+DMS as a session parallel to KDE; home-manager
|
||||||
|
scoped to user `finn`; a reusable `my.profiles.home-manager` module.
|
||||||
|
- **Out:** enabling on jupiter (headless server); Dank Greeter as the login
|
||||||
|
manager (SDDM stays); declarative DMS `settings.json` content (DMS is
|
||||||
|
configured through its own GUI at runtime; the HM `settings` option remains
|
||||||
|
available for later use but is left empty); any change to `configuration.nix`.
|
||||||
|
|
||||||
|
## Design
|
||||||
|
|
||||||
|
### 1. New flake inputs (`flake.nix`)
|
||||||
|
|
||||||
|
```nix
|
||||||
|
home-manager = {
|
||||||
|
url = "github:nix-community/home-manager";
|
||||||
|
inputs.nixpkgs.follows = "nixpkgs";
|
||||||
|
};
|
||||||
|
niri.url = "github:sodiboo/niri-flake";
|
||||||
|
dank.url = "github:AvengeMedia/DankMaterialShell";
|
||||||
|
```
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
- `dank` tracks nixos-unstable internally (its own `nixpkgs`), which is expected
|
||||||
|
for the DMS package build.
|
||||||
|
- `niri-flake` provides both the compositor session (nixosModule) and the HM
|
||||||
|
`programs.niri.settings` API that DMS's niri module extends.
|
||||||
|
- `home-manager` follows the repo `nixpkgs` (nixos-26.05).
|
||||||
|
|
||||||
|
`machines/configuration.nix` is **not** modified — the existing
|
||||||
|
`_module.args.inputs = self.inputs` line already makes these inputs reachable
|
||||||
|
from any module.
|
||||||
|
|
||||||
|
### 2. Home-manager profile (`modules/environments/home-manager/default.nix`)
|
||||||
|
|
||||||
|
A new opt-in `my.profiles.home-manager` profile. Because module `imports` cannot
|
||||||
|
be gated on an option value, the home-manager NixOS module is imported
|
||||||
|
unconditionally (harmless — it only adds options and does nothing until
|
||||||
|
`home-manager.users.*` is populated); only the global settings are guarded by
|
||||||
|
`mkIf cfg.enable`:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ config, lib, inputs, self, ... }:
|
||||||
|
let
|
||||||
|
cfg = config.my.profiles.home-manager;
|
||||||
|
in
|
||||||
|
{
|
||||||
|
imports = [ inputs.home-manager.nixosModules.home-manager ];
|
||||||
|
|
||||||
|
options.my.profiles.home-manager.enable =
|
||||||
|
lib.mkEnableOption "home-manager integration";
|
||||||
|
|
||||||
|
config = lib.mkIf cfg.enable {
|
||||||
|
home-manager.useGlobalPkgs = true; # HM shares the system pkgs (+ unstable overlay)
|
||||||
|
home-manager.useUserPackages = true;
|
||||||
|
home-manager.extraSpecialArgs = { inherit inputs self; };
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Registered by adding `./environments/home-manager` to
|
||||||
|
`modules/environments/default.nix`.
|
||||||
|
|
||||||
|
> Placement note: the profile lives under `modules/environments/` (where
|
||||||
|
> `my.profiles.*` modules live) to match the namespace, even though its function
|
||||||
|
> is infrastructural.
|
||||||
|
|
||||||
|
### 3. Dank profile (`modules/environments/dank/default.nix`)
|
||||||
|
|
||||||
|
Standard profile pattern; enables the home-manager profile as a dependency and
|
||||||
|
splits configuration between the system module (session + daemons) and the
|
||||||
|
home-manager module (keybinds / spawn / settings):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ config, lib, pkgs, inputs, ... }:
|
||||||
|
let
|
||||||
|
cfg = config.my.profiles.dank;
|
||||||
|
in
|
||||||
|
{
|
||||||
|
imports = [ inputs.dank.nixosModules.dank-material-shell ];
|
||||||
|
|
||||||
|
options.my.profiles.dank.enable = lib.mkEnableOption "DankMaterialShell on niri";
|
||||||
|
|
||||||
|
config = lib.mkIf cfg.enable {
|
||||||
|
# dependency: pull in home-manager integration
|
||||||
|
my.profiles.home-manager.enable = true;
|
||||||
|
|
||||||
|
# --- system side: niri session + DMS daemons/packages ---
|
||||||
|
programs.niri.enable = true; # niri-flake nixosModule → Wayland session in SDDM
|
||||||
|
|
||||||
|
programs.dank-material-shell = {
|
||||||
|
enable = true;
|
||||||
|
systemd.enable = true;
|
||||||
|
quickshell.package = pkgs.unstable.quickshell; # >= 0.3.0 from unstable
|
||||||
|
# enableSystemMonitoring / enableVPN / enableDynamicTheming / enableAudioWavelength
|
||||||
|
# / enableCalendarEvents all default true — left on.
|
||||||
|
};
|
||||||
|
|
||||||
|
# --- home side: DMS + niri keybinds for finn ---
|
||||||
|
home-manager.users.finn = {
|
||||||
|
imports = [
|
||||||
|
inputs.niri.homeModules.niri
|
||||||
|
inputs.dank.homeModules.dank-material-shell
|
||||||
|
inputs.dank.homeModules.niri
|
||||||
|
];
|
||||||
|
|
||||||
|
programs.dank-material-shell = {
|
||||||
|
enable = true;
|
||||||
|
systemd.enable = true;
|
||||||
|
quickshell.package = pkgs.unstable.quickshell;
|
||||||
|
niri.enableKeybinds = true; # Mod+Space launcher, Mod+V clipboard, media/brightness, power, lock…
|
||||||
|
niri.enableSpawn = true; # spawn `dms run` at niri startup
|
||||||
|
};
|
||||||
|
|
||||||
|
home.stateVersion = "26.05"; # match nixpkgs release; required by HM
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Registered by adding `./environments/dank` to
|
||||||
|
`modules/environments/default.nix`.
|
||||||
|
|
||||||
|
Open validation point (resolve during implementation, not a blocker):
|
||||||
|
- Confirm the exact HM output name for the niri integration
|
||||||
|
(`homeModules.niri` vs `homeModules.dankMaterialShell.niri`) and that
|
||||||
|
`programs.niri.enable` is the correct niri-flake nixosModule option; adjust to
|
||||||
|
match the pinned input revisions.
|
||||||
|
- Confirm whether `programs.dank-material-shell.quickshell.package` needs to be
|
||||||
|
set on both the system and HM sides or only one; set consistently.
|
||||||
|
|
||||||
|
### 4. Enable on mibook (`machines/mibook/environments.nix`)
|
||||||
|
|
||||||
|
Add to the `my.profiles` block:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
dank.enable = true;
|
||||||
|
```
|
||||||
|
|
||||||
|
KDE (`kde-desktop.enable = true`) stays; both sessions are offered by SDDM.
|
||||||
|
|
||||||
|
### 5. Documentation
|
||||||
|
|
||||||
|
No homepage dashboard entry (DMS is not a web service). CLAUDE.md is left
|
||||||
|
unchanged unless, after implementation, the home-manager pattern warrants a short
|
||||||
|
note — decided at the end, not up front (YAGNI).
|
||||||
|
|
||||||
|
## Data / control flow
|
||||||
|
|
||||||
|
1. `nixos-rebuild` builds the mibook toplevel; niri-flake registers a `niri`
|
||||||
|
Wayland session, DMS nixosModule installs packages + the `dms` user service
|
||||||
|
template, home-manager renders finn's niri config (with DMS keybinds) and DMS
|
||||||
|
config.
|
||||||
|
2. At login, SDDM lists **KDE** and **niri**. Selecting niri starts the
|
||||||
|
compositor; `spawn-at-startup` launches `dms run`, bringing up the DMS shell.
|
||||||
|
3. Keybinds invoke `dms ipc …` (launcher, clipboard, notifications, media,
|
||||||
|
brightness, power, lock). DMS is further configured via its own GUI, persisted
|
||||||
|
under `~/.config/DankMaterialShell/`.
|
||||||
|
|
||||||
|
## Risks / open questions
|
||||||
|
|
||||||
|
- **unstable/stable skew:** the repo pins nixos-26.05 while `dank` and
|
||||||
|
`niri-flake` track nixos-unstable, and quickshell comes from `pkgs.unstable`.
|
||||||
|
Qt6/quickshell version mismatch between the DMS package and the stable base is
|
||||||
|
the most likely failure. Mitigation: validate with a full toplevel build and,
|
||||||
|
if it fails, align quickshell/qt sourcing (e.g. take the DMS package's own
|
||||||
|
quickshell) before switching.
|
||||||
|
- **HM output/option names** may differ from the researched revision — pin the
|
||||||
|
inputs first, then read the resolved module options and adjust (see §3 open
|
||||||
|
validation point).
|
||||||
|
- **First HM activation** for finn: ensure `home.stateVersion` is set so the
|
||||||
|
build doesn't error.
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
1. `nix flake check` succeeds.
|
||||||
|
2. `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'`
|
||||||
|
succeeds.
|
||||||
|
3. `sudo nixos-rebuild test --flake '.#mibook'`, then log into the **niri**
|
||||||
|
session: DMS bar appears, `Mod+Space` opens the launcher, KDE session still
|
||||||
|
works.
|
||||||
Reference in New Issue
Block a user