diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..03f3f58 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,33 @@ +# Repository Guidelines + +## Project Structure & Module Organization +- `src/`: YAML "DNA" sources for the two schemes (`neon.yaml`, `aeon.yaml`). +- `templates//`: Jinja2 templates (`*.j2`) and optional `meta.yaml` that defines per-app output strategy. +- `dist/`: Generated theme outputs for each app; treat as build artifacts and do not edit by hand. +- `build.py`: Python build engine that renders templates into `dist/`. +- Docs and specs: `README.md`, `GEMINI.md`, `apex-neon.md`, `apex-aeon.md`. +- Assets: palette PNGs at repo root. + +## Build, Test, and Development Commands +- `uv run build.py` regenerates all themes from `src/` into `dist/` (requires Python 3.12+ and deps in `pyproject.toml`). +- There is no dev server or watch mode; rerun the build after updating YAML or templates. + +## Coding Style & Naming Conventions +- Python code follows 4-space indentation and `snake_case` for functions/variables. +- Template outputs follow the naming pattern `apex-.` for per-scheme builds. +- Aggregated outputs (when `meta.yaml` sets `strategy: aggregated`) keep the template base name (e.g., `apex.json`, `gtk.css`). +- Keep YAML keys consistent with existing `src/*.yaml` semantics; add new roles only if they are truly required. + +## Testing Guidelines +- No automated tests are currently defined. +- Validate changes by running `uv run build.py` and checking the generated files in `dist/` for both Neon and Aeon outputs. + +## Commit & Pull Request Guidelines +- Commit messages follow Conventional Commits as seen in history: `feat:`, `docs:`, `chore:`, `refactor:`. +- Keep changes scoped to one intent; prefer small, reviewable commits. +- PRs should include a short summary, list of affected templates/apps, and the command used to build (`uv run build.py`). +- For visual/theme changes, include a brief before/after note or screenshots when possible. + +## Theme Rules & Source of Truth +- `GEMINI.md` is the authoritative source for color semantics and rules; update `src/*.yaml` first, then templates if needed. +- Avoid introducing ad-hoc colors that violate the semantic palette. diff --git a/INSTALL.md b/INSTALL.md index efce256..2960a9d 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -124,241 +124,116 @@ All generated theme files can be found in the `dist/` directory after running `u **Installation:** 1. This file maps Apex colors to Libadwaita named colors (`@window_bg_color`, etc.). 2. Copy or symlink it to your GTK4 config directory: - - ```bash - - # For standard GTK4 apps - - mkdir -p ~/.config/gtk-4.0 - - ln -s $(pwd)/dist/gtk4/gtk.css ~/.config/gtk-4.0/gtk.css - - ``` - - 3. To apply changes immediately, you may need to restart your applications or log out/in. - - - - --- - - - - ## 8. Hyprland - - - - **Files:** - - - `dist/hyprland/apex-neon-colors.conf` - - - `dist/hyprland/apex-aeon-colors.conf` - - - - **Installation:** - - 1. Copy the files to your Hyprland config directory: - - ```bash - - cp dist/hyprland/*.conf ~/.config/hypr/ - - ``` - - 2. Source the desired theme in your `hyprland.conf`: - - ```conf - - source = ~/.config/hypr/apex-neon-colors.conf - - # source = ~/.config/hypr/apex-aeon-colors.conf - - ``` - - - - --- - - - - ## 9. Fuzzel - - - - **Files:** - - - `dist/fuzzel/apex-neon-fuzzel.ini` - - - `dist/fuzzel/apex-aeon-fuzzel.ini` - - - - **Installation:** - - 1. Copy the desired file to your Fuzzel config location: - - ```bash - - cp dist/fuzzel/apex-neon-fuzzel.ini ~/.config/fuzzel/fuzzel.ini - - ``` - - 2. Alternatively, use the `--config` flag when launching Fuzzel. - - - - --- - - - - ## 10. Waybar - - - - **Files:** - - - `dist/waybar/apex-neon-colors.css` - - - `dist/waybar/apex-aeon-colors.css` - - - - **Installation:** - - 1. Copy the desired file to your Waybar config directory: - - ```bash - - cp dist/waybar/apex-neon-colors.css ~/.config/waybar/colors.css - - ``` - - 2. Import it in your main `style.css`: - - ```css - - @import "colors.css"; - - ``` - - 3. Use the variables in your CSS (e.g., `background-color: @background;`, `color: @foreground;`, `border-color: @accent;`). - - - - --- - - - - ## 11. Zathura - - - - **Files:** - - - `dist/zathura/apex-neon-zathurarc` - - - `dist/zathura/apex-aeon-zathurarc` - - - - **Installation:** - - 1. Copy the desired file to your Zathura config directory: - - ```bash - - mkdir -p ~/.config/zathura - - cp dist/zathura/apex-neon-zathurarc ~/.config/zathura/zathurarc - - ``` - - 2. Or include it in your existing config: - - ```conf - - include apex-neon-zathurarc - - ``` - - - - --- - - - - ## 12. Btop - - - - **Files:** - - - `dist/btop/apex-neon.theme` - - - `dist/btop/apex-aeon.theme` - - - - **Installation:** - - 1. Copy the desired file to your Btop themes directory (usually `~/.config/btop/themes/`): - - ```bash - - mkdir -p ~/.config/btop/themes - - cp dist/btop/*.theme ~/.config/btop/themes/ - - ``` - - 2. Select the theme within Btop settings (ESC -> Options -> Color theme). - - - - --- - - - - ## 13. SwayNC - - - - **Files:** - - - `dist/swaync/apex-neon-style.css` - - - `dist/swaync/apex-aeon-style.css` - - - - **Installation:** - - 1. Copy the desired file to your SwayNC config directory: - - ```bash - - mkdir -p ~/.config/swaync - - cp dist/swaync/apex-neon-style.css ~/.config/swaync/style.css - - ``` - - 2. Reload SwayNC: - - ```bash - - swaync-client -rs - - ``` - - - - - - - - - - - - \ No newline at end of file + ```bash + # For standard GTK4 apps + mkdir -p ~/.config/gtk-4.0 + ln -s $(pwd)/dist/gtk4/gtk.css ~/.config/gtk-4.0/gtk.css + ``` +3. To apply changes immediately, you may need to restart your applications or log out/in. + +--- + +## 8. Hyprland + +**Files:** +- `dist/hyprland/apex-neon-colors.conf` +- `dist/hyprland/apex-aeon-colors.conf` + +**Installation:** +1. Copy the files to your Hyprland config directory: + ```bash + cp dist/hyprland/*.conf ~/.config/hypr/ + ``` +2. Source the desired theme in your `hyprland.conf`: + ```conf + source = ~/.config/hypr/apex-neon-colors.conf + # source = ~/.config/hypr/apex-aeon-colors.conf + ``` + +--- + +## 9. Fuzzel + +**Files:** +- `dist/fuzzel/apex-neon-fuzzel.ini` +- `dist/fuzzel/apex-aeon-fuzzel.ini` + +**Installation:** +1. Copy the desired file to your Fuzzel config location: + ```bash + cp dist/fuzzel/apex-neon-fuzzel.ini ~/.config/fuzzel/fuzzel.ini + ``` +2. Alternatively, use the `--config` flag when launching Fuzzel. + +--- + +## 10. Waybar + +**Files:** +- `dist/waybar/apex-neon-colors.css` +- `dist/waybar/apex-aeon-colors.css` + +**Installation:** +1. Copy the desired file to your Waybar config directory: + ```bash + cp dist/waybar/apex-neon-colors.css ~/.config/waybar/colors.css + ``` +2. Import it in your main `style.css`: + ```css + @import "colors.css"; + ``` +3. Use the variables in your CSS (e.g., `background-color: @background;`, `color: @foreground;`, `border-color: @accent;`). + +--- + +## 11. Zathura + +**Files:** +- `dist/zathura/apex-neon-zathurarc` +- `dist/zathura/apex-aeon-zathurarc` + +**Installation:** +1. Copy the desired file to your Zathura config directory: + ```bash + mkdir -p ~/.config/zathura + cp dist/zathura/apex-neon-zathurarc ~/.config/zathura/zathurarc + ``` +2. Or include it in your existing config: + ```conf + include apex-neon-zathurarc + ``` + +--- + +## 12. Btop + +**Files:** +- `dist/btop/apex-neon.theme` +- `dist/btop/apex-aeon.theme` + +**Installation:** +1. Copy the desired file to your Btop themes directory (usually `~/.config/btop/themes/`): + ```bash + mkdir -p ~/.config/btop/themes + cp dist/btop/*.theme ~/.config/btop/themes/ + ``` +2. Select the theme within Btop settings (ESC -> Options -> Color theme). + +--- + +## 13. SwayNC + +**Files:** +- `dist/swaync/apex-neon-style.css` +- `dist/swaync/apex-aeon-style.css` + +**Installation:** +1. Copy the desired file to your SwayNC config directory: + ```bash + mkdir -p ~/.config/swaync + cp dist/swaync/apex-neon-style.css ~/.config/swaync/style.css + ``` +2. Reload SwayNC: + ```bash + swaync-client -rs + ```