Cybrland: Building a Design System for Your Desktop Environment
Hook
Most developers treat their dotfiles as a dumping ground for configuration snippets copied from Stack Overflow. Cybrland flips this model by starting with a design system—a unified color palette and visual language—then building 17+ application themes that reference it as a single source of truth.
Context
The Linux desktop customization community has a dirty secret: despite thousands of dotfiles repositories on GitHub, most are either monolithic dumps of personal configs with hardcoded values, or minimal starter templates that leave aesthetics as an exercise for the reader. The middle ground—modular, well-documented configurations that demonstrate how to build cohesive theming across disparate applications—is surprisingly rare.
This gap is particularly acute in the Wayland ecosystem. As users migrate from X11 window managers like i3 or bspwm to Wayland compositors like Hyprland or Sway, they discover that their carefully curated ricing workflows don’t translate directly. Wayland’s security model breaks X11 tools, forcing users to find alternatives for everything from status bars (polybar → waybar) to screenshot utilities (maim → grim). Cybrland emerged as a response to this migration pain point: a complete reference implementation showing how to theme a modern Wayland-based desktop while maintaining the terminal-centric, keyboard-driven workflows that power users expect.
Technical Insight
The architectural centerpiece of Cybrland is Cybrcolors, a custom color system that functions as a design token library. Rather than scattering color values across individual application configs, Cybrland defines a palette once and references it everywhere. This isn’t just about aesthetics—it’s about maintainability. When you want to adjust your accent color, you modify a single source file rather than hunting through dozens of configs.
The color system demonstrates a sophisticated understanding of theming hierarchy. Looking at the Waybar configuration, you’ll see it doesn’t hardcode #ff00ff for magenta—instead, it references semantic color names that map to the Cybrcolors palette:
/* waybar/style.css */
@define-color background #0a0e14;
@define-color foreground #b3b1ad;
@define-color accent-primary #ff2e97;
@define-color accent-secondary #00d9ff;
@define-color warning #ffb454;
@define-color critical #ff3333;
#workspaces button.active {
background: @accent-primary;
color: @background;
}
#battery.warning {
color: @warning;
}This approach mirrors modern frontend development practices—think CSS custom properties or design tokens in systems like Tailwind or Material Design. The payoff is consistency without rigidity. Each application speaks the same visual language, but implementations vary based on the tool’s capabilities. Waybar uses CSS, kitty uses its own config format, and fish shell uses escape sequences, yet all reference the same color values.
The shell scripting layer reveals another architectural choice: treating the desktop environment as a programmable system rather than a collection of static configs. Cybrland includes scripts that dynamically switch wallpapers, coordinate theme changes across applications, and manage Hyprland workspaces. The wallpaper switcher demonstrates this philosophy:
#!/bin/bash
# scripts/wallpaper-switcher.sh
WALLPAPER_DIR="$HOME/.config/hypr/cybrpapers"
CURRENT=$(cat ~/.cache/current_wallpaper 2>/dev/null || echo "")
# Get random wallpaper different from current
WALLPAPERS=("$WALLPAPER_DIR"/*.png)
NEW_WALLPAPER="${WALLPAPERS[RANDOM % ${#WALLPAPERS[@]}]}"
while [[ "$NEW_WALLPAPER" == "$CURRENT" ]] && [[ ${#WALLPAPERS[@]} -gt 1 ]]; do
NEW_WALLPAPER="${WALLPAPERS[RANDOM % ${#WALLPAPERS[@]}]}"
done
# Use swww for smooth transitions
swww img "$NEW_WALLPAPER" --transition-type fade --transition-duration 2
echo "$NEW_WALLPAPER" > ~/.cache/current_wallpaper
# Notify user
notify-send "Cybrland" "Wallpaper changed" -i "$NEW_WALLPAPER"This script doesn’t just change wallpapers—it maintains state, ensures variety, and provides user feedback. It’s infrastructure code for your desktop, treating visual elements as stateful resources that can be queried and manipulated programmatically.
The modular architecture deserves special attention because it solves a real problem in dotfiles distribution: the all-or-nothing installation trap. Cybrland structures each application theme as a self-contained unit with its own README, dependencies list, and installation instructions. Want just the rofi theme without adopting the entire Hyprland config? The rofi directory is a standalone package that works independently. This modularity is enforced through careful separation of concerns—no application config reaches into another’s directory structure or assumes the presence of other components beyond the shared Cybrcolors palette.
The documentation strategy is equally sophisticated. Rather than a single monolithic README, Cybrland provides contextual documentation at every level: a project overview in the root, component-specific guides in subdirectories, and inline comments in configs explaining non-obvious choices. The Waybar README, for instance, doesn’t just list installation steps—it explains why certain modules are configured the way they are, what alternatives exist, and how to extend the setup. This documentation-as-teaching approach transforms the repository from a personal config dump into an educational resource.
Gotcha
The platform constraints are significant and non-negotiable. Cybrland assumes Arch Linux, Hyprland, and a specific ecosystem of tools. While the color system and design principles are portable, the actual configurations are tightly coupled to this stack. The Hyprland config references features specific to that compositor, the Waybar modules assume systemd for service management, and installation instructions use pacman/yay for package management. Porting to Ubuntu + Sway would require substantial adaptation—not just find-and-replace, but rethinking how components interact.
The work-in-progress components expose another limitation: scope ambition outpacing implementation bandwidth. The Neovim config is marked WIP, Firefox theming is incomplete, and GTK application integration is partial. This creates an uncanny valley where some applications feel meticulously crafted while others break the visual illusion. For users expecting a fully cohesive experience out of the box, these gaps are jarring. The cyberpunk aesthetic itself is polarizing—it’s maximalist, neon-saturated, and deliberately aggressive. If your professional context requires subdued visuals for screen sharing, or you simply prefer Nordic minimalism, Cybrland’s entire premise works against you.
Verdict
Use if: You’re running Arch + Hyprland and want to learn how to build systematic, maintainable desktop theming rather than just copying configs blindly. Cybrland excels as an educational resource and reference implementation—even if you don’t love cyberpunk aesthetics, the architecture demonstrates professional-grade dotfiles organization. It’s also ideal if you’re migrating from X11 to Wayland and need a complete working example of the modern stack (waybar, rofi-wayland, swww, grim/slurp). Skip if: You’re on a different distribution or compositor (porting effort exceeds building from scratch), you need production-stable configs for all components immediately (several themes are WIP), or you prefer minimal aesthetics and would spend more time undoing Cybrland’s visual choices than benefiting from its structure. Also skip if you’re GUI-first rather than terminal-centric—Cybrland assumes you live in kitty with fish/yazi/btop, not Firefox with a file manager.
