Requirements:

• One of the compositors:
  • YaLTeR/niri, a scrollable-tiling Wayland compositor.
  • hyprwm/Hyprland, an independent, highly customizable, dynamic tiling Wayland compositor.
• ignis-sh/ignis, a widget framework for building desktop shells.
  • Currently the latest main branch should be installed.
• Blueprint, a markup language for GTK user interfaces.
• libadwaita, building blocks for modern GNOME applications.
• Tela icon theme, a flat colorful design icon theme.
  • Without tela installed, some icons might be missing.

• Adw is initialized in config.py and is required for ui styles, light/dark color schemes, and is used in some widgets.
• Blueprint is used in most views and widgets, so can be tweaked as wish. They are built during class declarations.
  • An example is to use grid layout in AppLauncher by replacing ListView by GridView in its .blp file. Some declarations in the .py file should also be replaced accordingly.
  • Don't forget to run ignis reload after editing blueprints.
• AppLauncher is initialized in config.py and can be disabled by commenting it out.
  • Don't forget to also edit the launcher command in topbar buttons.
• Notification service is required in NotificationPopups and ControlCenter.
  • NotificationPopups can be disabled by commenting it out in config.py.
  • NotificationCenter can be removed from ControlCenter's blueprint file.
• WallpaperWindows are initialized in config.py, and can be commented out if other wallpaper services are used.
  • For niri, an extra WallpaperWindow is initialized as the overview backdrop, which should also be configured in niri (example below).
• OSD displays changes of volumes, backlight, and optionally caps lock state.
  • libevdev is required for caps lock state detection, installed via system package manager and pip.
    • Install libevdev: pacman -S libevdev.
    • Install Python bindings: pacman -S python-libevdev or pip install libevdev.
  • User should also be a member of group input for libevdev to work.

• As is stated, this project works under niri and Hyprland, and synchronizes windows and workspaces in addition to their focus states. These functions are designed as three widgets: a workspaces pill, a focused window indicator, and a dock.
• Recommended keybindings (which should be configured in niri or Hyprland):
  • Toggle App Launcher: ignis toggle-window ignis-applauncher.
    • It is recommended to also have a fallback launcher, since we are unstable now.
  • Toggle Control Center: ignis toggle-window ignis-controlcenter.
  • Run custom commands with ignis run-command:
    • Start/stop Screen Recorder: ignis run-command toggle-recording.
    • Toggle Dock Auto Hide: ignis run-command toggle-dock.
    • List all available commands: ignis list-commands.
  • Note: if the ignis CLI is slow for you, try goignis.
• Layer window rules:
  • Under niri, layer-rule can match namespace with ignis-applauncher, ignis-controlcenter, ignis-topbar and ignis-appdock.
  • Under Hyprland, layerrule is used instead.
  • Hyprland should disable window enter animations for App Launcher and Control Center, as they already have a Revealer transition inside.
  • Window shadow often cares the border radius, which is defined as var(--window-border-radius), which is provided by libadwaita.

• Shortcuts in App Launcher:

  • Toggle search bar: Control-f.
  • Close launcher window: Esc, or Control-[.
  • Select next: Down, Control-j, or Control-n.
  • Select previous: Up, Control-k, or Control-p.
  • Page Up/Down: PageUp, PageDown.

• Styles:

  • CSS variables and classes from libadwaita can be used in .blp files.
  • Some css classes are also generated in TailWindCSS style to be used in .blp designs, e.g. px-2, m-1.
  • If that's not enough, more style definitions can be added into styles.scss.

• Designs:

  • It should be easy to read and edit .blp files, but don't break widget names and callbacks that are needed in widgets' codes.

• Widgets:

  • Some widgets are designed to be used and customized in anywhere of .blp files.
  • CommandPill: a Gtk.Button that accepts an additional click-command property to be run upon clicked.
  • ControlSwitchCmd: a ControlSwitch that are used to toggle service up and down in ControlCenter, e.g. wlsunset.

• Configure BackdropWallpaper in niri:

  layer-rule {
      match namespace="^ignis_wallpaper_backdrop_.*$"
      place-within-backdrop true
      opacity 0.5
  }
  layer-rule {
      match namespace="^ignis_wallpaper_service_.*$"
      baba-is-float true
  }

I personally use neovim for coding. With pyright, ruff, blueprint-compiler installed, and with typing stubs, LSP, code formatter configured, it should be easy to work with.

An example pyproject.toml:

[tool.pyright]
# ignis is installed at venv "/path/to/venv/lib/ignis"
venvPath = "/path/to/venv/lib"
venv = "ignis"

[tool.ruff]
line-length = 120
target-version = "py313"

[tool.ruff.format]
skip-magic-trailing-comma = true
docstring-code-format = true