Replace swaylock with gtklock; centralise theme palette

- Replace swaylock with gtklock (username + password form lockscreen) - Add gtklock/config.ini and gtklock/style.css (Tomorrow Night theme) - Update niri keybindings and swayidle to invoke gtklock -d - Update packages.txt: swaylock -> gtklock - Update install.sh: add AUR helper detection (yay/paru), symlink gtklock configs - Add theme/colors.css (CSS custom properties) and theme/colors.json - Update waybar/style.css, wofi/style.css, gtklock/style.css to import shared palette - Update README.md with project summary and component table - Add ARCHITECTURE.md and CLAUDE.md
2026-04-24 12:56:58 -07:00
parent 8c099437a4
commit 8be00bc273
12 changed files with 668 additions and 31 deletions
@@ -0,0 +1,204 @@
+# CLAUDE.md
+
+## Purpose
+
+This repository defines a complete Wayland desktop environment built around **Niri**, with a focus on:
+
+* Simplicity
+* Reproducibility
+* Fast startup
+* Low cognitive overhead
+* Clean separation of concerns
+
+Claude should act as a **systems engineer**, not just a script generator.
+
+---
+
+## Core Principles
+
+### 1. Single Source of Truth
+
+* All configuration lives in `~/.config` via symlinks
+* No duplication across tools
+* Shared values (theme, fonts, gaps, etc.) should be centralized
+
+### 2. Idempotent Setup
+
+* `install.sh` must be safe to re-run
+* No destructive operations without explicit flags
+* Detect and skip existing correct state
+
+### 3. Composability
+
+* Each tool (waybar, mako, wofi, etc.) is independent
+* No hidden coupling unless explicitly documented
+
+### 4. Declarative > Imperative
+
+* Prefer static config over runtime scripts
+* Avoid background daemons unless required
+
+---
+
+## Expected Claude Behavior
+
+When modifying this repo, Claude should:
+
+### Configuration Changes
+
+* Keep configs minimal and readable
+* Avoid introducing magic or implicit behavior
+* Prefer explicit keybindings and comments
+
+### Adding Features
+
+* Justify *why* the feature exists
+* Ensure it fits Wayland + Niri workflow
+* Avoid X11 dependencies unless unavoidable
+
+### Refactoring
+
+* Reduce duplication across configs
+* Extract shared values (colors, fonts, spacing)
+* Keep file structure intuitive
+
+---
+
+## Directory Expectations
+
+```
+dotfiles/
+├── config/
+│   ├── niri/
+│   ├── waybar/
+│   ├── alacritty/
+│   ├── fish/
+│   ├── starship/
+│   ├── wofi/
+│   ├── mako/
+│   ├── gtklock/
+│   └── ...
+├── install.sh
+├── packages.txt
+└── README.md
+```
+
+---
+
+## Tooling Rules
+
+### Niri
+
+* All keybindings must be defined here
+* Window rules must be deterministic
+* Avoid runtime scripting where possible
+
+### Waybar
+
+* Keep modules minimal
+* Prefer JSON config over scripts
+* Avoid polling when event-based is possible
+
+### Fish + Starship
+
+* Fast startup is critical
+* No blocking operations
+* Avoid heavy plugins
+
+### Wofi
+
+* Keep styling consistent with GTK theme
+* Avoid unnecessary wrappers
+
+### Mako
+
+* Notifications should be minimal and non-intrusive
+* Timeout defaults should be short
+
+---
+
+## Theming
+
+Theme: **Tomorrow Night**
+
+Ensure consistency across:
+
+* GTK (Materia-dark)
+* Icons (Papirus)
+* Terminal (Alacritty)
+* Waybar
+* Wofi
+
+Claude should:
+
+* Reuse the same color palette everywhere
+* Avoid hardcoding colors in multiple places
+
+---
+
+## Install Script Expectations
+
+`install.sh` must:
+
+1. Symlink configs into `~/.config`
+2. Install packages from `packages.txt`
+3. Detect distro (Arch-based assumed unless specified)
+4. Fail fast on errors
+5. Print clear status messages
+
+---
+
+## Anti-Patterns (DO NOT DO)
+
+* ❌ Duplicate configs across tools
+* ❌ Add large frameworks or dependencies
+* ❌ Introduce race conditions in startup
+* ❌ Use sleep-based timing hacks
+* ❌ Hardcode machine-specific paths
+
+---
+
+## Safe Enhancements
+
+Claude may suggest:
+
+* Shared theme variables
+* Config generation (if simple and transparent)
+* Modular config structure
+* Performance improvements (startup, memory)
+
+---
+
+## Testing Expectations
+
+After changes:
+
+* Niri starts without errors
+* Waybar loads correctly
+* No missing fonts/icons
+* No broken keybindings
+* No noticeable startup delay
+
+---
+
+## Output Style
+
+When generating code:
+
+* Provide complete files (not fragments)
+* Keep formatting clean
+* Avoid unnecessary comments
+* Prefer clarity over cleverness
+
+---
+
+## Summary
+
+This is a **minimal, fast, reproducible Wayland environment**.
+
+Claude’s role is to:
+
+* Maintain clarity
+* Prevent bloat
+* Improve consistency
+* Keep everything predictable