docs: fix INSTALL formatting and add AGENTS guide
This commit is contained in:
s0wlz (Matthias Puchstein)
33
AGENTS.md
Normal file
33
AGENTS.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Repository Guidelines
|
||||
|
||||
## Project Structure & Module Organization
|
||||
- `src/`: YAML "DNA" sources for the two schemes (`neon.yaml`, `aeon.yaml`).
|
||||
- `templates/<app>/`: 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-<scheme>.<ext>` 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.
|
||||
351
INSTALL.md
351
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
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user