███╗   ██╗ ██████╗  ██████╗████████╗██████╗  █████╗      ██████╗ ███████╗
████╗  ██║██╔═══██╗██╔════╝╚══██╔══╝██╔══██╗██╔══██╗    ██╔═══██╗██╔════╝
██╔██╗ ██║██║   ██║██║        ██║   ██████╔╝███████║    ██║   ██║███████╗
██║╚██╗██║██║   ██║██║        ██║   ██╔══██╗██╔══██║    ██║   ██║╚════██║
██║ ╚████║╚██████╔╝╚██████╗   ██║   ██║  ██║██║  ██║    ╚██████╔╝███████║
╚═╝  ╚═══╝ ╚═════╝  ╚═════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝     ╚═════╝ ╚══════╝

A dark, modular Hyprland desktop for the obsessive minimalist

---

✦ Overview

Noctra OS is a fully modular, performance-tuned Hyprland configuration built on Arch Linux. It's designed around a single philosophy: everything that touches the screen should be intentional.

The result is a clean dark desktop that stays out of your way — with a Dynamic Island-style Waybar notch, a Material You color system driven by your wallpaper via Matugen, and a shell that loads in milliseconds.

🖼️ Screenshots

Desktop	Notification Center

⚙️ Tech Stack

Component	Tool	Notes
OS	Arch Linux	Rolling release, minimal base
Window Manager	Hyprland	Dynamic tiling, Wayland-native
Bar	Waybar	Custom Dynamic Island notch
Notifications	SwayNC	Control center + notification daemon
Terminal	Kitty	GPU-accelerated, ligature support
Shell	Zsh + Starship	Fast, lazy-loaded plugins
App Launcher	Rofi	Multi-style launcher themes
Wallpaper	awww (formerly swww)	Smooth animated transitions
Color Engine	Matugen	Material You wallpaper-driven theming
File Manager	Thunar	Lightweight GTK file manager
System Monitor	btop	Resource monitor, custom themed
Audio Visualizer	cava	Terminal-based spectrum analyzer
Fetch	fastfetch	System info on shell launch
OSD	swayosd	On-screen volume/brightness display
Hardware	AMD Ryzen 5 (iGPU)	All settings tuned for integrated graphics

✨ Features

🏝️ Dynamic Island Waybar

The bar is styled as a notch that drops from the top edge of the screen — no floating pills, no side panels. Everything lives in a single center module group with a border-radius: 0 0 25px 25px hanging shape. Jitter-free workspace buttons use a fixed min-width to prevent layout shifts.

🎨 Full Material You Theming with Matugen

Every application — Waybar, SwayNC, Kitty, Hyprland borders, Rofi, btop, cava, fastfetch — is themed from a single source of truth: your wallpaper. Running matugen image <wallpaper> regenerates all color files simultaneously. No manual hex-editing, ever.

Wallpaper → Matugen → colors.css / colors.conf → All Apps

🧩 Modular Hyprland Config

The main hyprland.conf is purely a source manifest. Each concern lives in its own file:

hypr/
├── hyprland.conf     # Entry point — sources only
├── look.conf         # Gaps, borders, blur, shadows, rounding
├── animation.conf    # Bezier curves and animation speeds
├── keybindings.conf  # All binds in one place
├── autostart.conf    # exec-once daemons
├── env.conf          # Wayland/Qt/SDL environment vars
├── input.conf        # Keyboard, touchpad, gestures
├── layout.conf       # Master/dwindle layout settings
├── misc.conf         # VFR, DPMS, logo suppression
├── monitors.conf     # Display resolution and scaling
├── rules.conf        # Window rules
└── colors.conf       # Auto-generated by Matugen — do not edit

⚡ Performance-First Shell

The .zshrc is built for speed:

• Lazy NVM loading — nvm, node, npm, npx, and yarn are stubs that bootstrap the real NVM only on first use
• Cached completions — compinit only re-runs if .zcompdump is older than 24 hours
• Plugin order enforced — autosuggestions before syntax highlighting (required for correct render)
• Matugen-aware highlights — zsh-syntax-highlighting uses Kitty's ANSI palette, which Matugen has already set from your wallpaper

📦 Dependencies

Core (required)

# Wayland / Hyprland
hyprland waybar swaync swayosd awww hyprlock hypridle

# Terminal & Shell
kitty zsh starship

# Launcher & Tools
rofi-wayland grim slurp thunar polkit-gnome

# Theming
matugen ttf-jetbrains-mono-nerd

# System
btop cava fastfetch playerctl brightnessctl

AUR packages

# Using paru or yay
paru -S matugen-bin awww-git swayosd-git

🚀 Installation

⚠️ Back up your existing ~/.config before proceeding.

# 1. Clone the repository
git clone https://github.com/Blaze2216/dotfiles.git ~/dotfiles

# 2. Copy configs
cp -r ~/dotfiles/.config/* ~/.config/
cp ~/dotfiles/zsh/.zshrc ~/.zshrc

# 3. Install dependencies (Arch)
sudo pacman -S hyprland waybar swaync kitty zsh starship \
  rofi-wayland grim thunar btop cava fastfetch playerctl brightnessctl

# 4. Install AUR packages
paru -S matugen-bin awww-git swayosd-git

# 5. Set your wallpaper and generate colors
matugen image ~/Pictures/wallpapers/your-wallpaper.jpg

# 6. Launch Hyprland
Hyprland

🎨 Theming Your Wallpaper

Noctra OS is designed to be re-themed in a single command. The wall alias makes this instant:

# From anywhere in your shell
awww img ~/Pictures/wallpapers/your-image.jpg

This runs matugen image which:

1. Extracts a Material You color palette from the image
2. Regenerates waybar/colors.css, hypr/colors.conf, kitty/colors.conf, rofi/colors.rasi, btop/themes/noctra.theme, cava/config, and fastfetch/config.jsonc
3. You can then reload Waybar with SUPER + R or the refresh alias

To fully apply including borders, restart Hyprland or run:

hyprctl reload && pkill -USR2 waybar

⌨️ Keybindings

Action	Shortcut
Launch Terminal	SUPER + Enter
Kill Window	SUPER + Q
App Launcher	SUPER + A
File Manager	SUPER + E
Firefox	SUPER + B
Toggle Floating	SUPER + V
Scratchpad Toggle	SUPER + S
Move to Scratchpad	SUPER + SHIFT + S
Screenshot (full)	Print
Reload Waybar	SUPER + R
Apply Wallpaper + Theme	SUPER + SHIFT + W
Exit / Shutdown	SUPER + M
Focus (Arrow Keys)	SUPER + ←↑↓→
Move to Workspace	SUPER + 1–0
Move Window to Workspace	SUPER + SHIFT + 1–0
Volume Up / Down	XF86AudioRaiseVolume / Lower
Mute	XF86AudioMute
Brightness Up / Down	XF86MonBrightnessUp / Down
Media Play/Pause/Skip	XF86Audio*

🗂️ Full Directory Structure

dotfiles/
├── .config/
│   ├── hypr/               # Hyprland WM config (modular)
│   ├── waybar/             # Bar config + Matugen CSS output
│   ├── swaync/             # Notification center + scripts
│   ├── kitty/              # Terminal config + colors
│   ├── matugen/            # Color templates for all apps
│   │   └── templates/      # .css/.conf/.jsonc templates
│   ├── rofi/               # App launcher styles (7 types, 15 styles)
│   ├── btop/               # System monitor + themed config
│   ├── cava/               # Audio visualizer + shaders
│   └── fastfetch/          # System fetch config + ASCII art
└── zsh/
    └── .zshrc              # Zsh config with lazy-loaded plugins

🔧 Useful Aliases

Alias	Command	Description
wall <img>	matugen image	Set wallpaper and regenerate all colors
refresh	pkill -USR2 waybar	Reload Waybar in place
update	sudo pacman -Syu	Full system upgrade
install	sudo pacman -S	Install package
v	nvim	Open Neovim
ls	eza --icons	Better ls with icons
ll	eza -lah --icons	Long listing with icons

📝 Notes & Known Quirks

• Colors are auto-generated. ~/.config/hypr/colors.conf, ~/.config/waybar/colors.css, and similar files are overwritten by Matugen — don't edit them manually.
• Monitor config is set for eDP-1 at 1920x1080@60 with 1.25 scaling. Edit hypr/monitors.conf to match your display.
• Wallpaper path in the SUPER + SHIFT + W keybind is hardcoded. Edit keybindings.conf to point to your own wallpaper.
• AMD iGPU tuning: Blur is set to 3 passes at size 6, shadows at render_power 1. If you have a dedicated GPU, you can increase these for a richer look.

🙏 Acknowledgements

• Hyprland — for making Wayland actually enjoyable
• Matugen — for the Material You theming engine
• Waybar — for being endlessly configurable
• r/unixporn — for the endless inspiration

---

Built with obsession on Arch Linux · Noctra OS by Blaze