refactor: consolidate app configurations and utility scripts
- Move 32+ app-specific scripts from features/apps/scripts/ to features/scripts/utils/ for centralized packaging. - Create individual Nix modules for orphaned app configurations (btop, kitty, tmux, etc.) in features/apps/ using xdg.configFile. - Fix broken paths in core/system/makima.nix and features/apps/vscode.nix. - Update VSCode configuration to use the modern 'profiles.default.userSettings' API, resolving deprecation warnings. - Merge duplicate 'nomarchy-launch-walker' scripts into a single robust utility. - Remove stale root 'config/' directory. - Update README.md and docs/creating-themes.md to reflect the new architecture and keybindings. - Ensure all modules are correctly imported and verified via nix flake check.
This commit is contained in:
Bernardo Magri
230
docs/creating-themes.md
Normal file
230
docs/creating-themes.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# Creating a Nomarchy Theme
|
||||
|
||||
This guide walks through creating a new theme for Nomarchy from scratch.
|
||||
|
||||
## Theme Directory Structure
|
||||
|
||||
Each theme lives in `themes/palettes/<theme-name>/` with the following structure:
|
||||
|
||||
```
|
||||
themes/palettes/my-theme/
|
||||
├── colors.toml # REQUIRED - Color palette definition
|
||||
├── icons.theme # REQUIRED - GTK icon theme name (single line)
|
||||
├── light.mode # Optional - Empty marker file for light themes
|
||||
├── preview.png # Optional - Preview image for the theme selector
|
||||
├── backgrounds/ # Optional - Wallpaper images
|
||||
│ ├── 1-primary.jpg # Numbered prefix controls default order
|
||||
│ ├── 2-alternate.png
|
||||
│ └── ...
|
||||
└── apps/ # Optional - App-specific themed configs
|
||||
├── btop.theme # btop color theme
|
||||
├── neovim.lua # Neovim colorscheme plugin spec
|
||||
├── vscode.json # VS Code theme extension reference
|
||||
└── hyprland.conf # Hyprland visual overrides (colors, decorations, animations)
|
||||
```
|
||||
|
||||
## Step 1: Create the Color Palette
|
||||
|
||||
Create `colors.toml` with all 24 required color fields. Every color must be a hex value with a `#` prefix.
|
||||
|
||||
```toml
|
||||
# UI colors
|
||||
accent = "#83b6af"
|
||||
cursor = "#d3c6aa"
|
||||
foreground = "#d3c6aa"
|
||||
background = "#2d353b"
|
||||
selection_foreground = "#d3c6aa"
|
||||
selection_background = "#505a60"
|
||||
|
||||
# ANSI 16-color palette (color0-15)
|
||||
# Normal colors
|
||||
color0 = "#3c474d" # Black
|
||||
color1 = "#e68183" # Red
|
||||
color2 = "#a7c080" # Green
|
||||
color3 = "#d9bb80" # Yellow
|
||||
color4 = "#83b6af" # Blue
|
||||
color5 = "#d39bb6" # Magenta
|
||||
color6 = "#87c095" # Cyan
|
||||
color7 = "#868d80" # White
|
||||
|
||||
# Bright colors
|
||||
color8 = "#868d80" # Bright Black
|
||||
color9 = "#e68183" # Bright Red
|
||||
color10 = "#a7c080" # Bright Green
|
||||
color11 = "#d9bb80" # Bright Yellow
|
||||
color12 = "#83b6af" # Bright Blue
|
||||
color13 = "#d39bb6" # Bright Magenta
|
||||
color14 = "#87c095" # Bright Cyan
|
||||
color15 = "#868d80" # Bright White
|
||||
```
|
||||
|
||||
These colors are mapped to a Base16 palette automatically:
|
||||
|
||||
| Base16 Slot | Source Field | Typical Role |
|
||||
|-------------|---------------|----------------------------|
|
||||
| base00 | background | Default background |
|
||||
| base01 | color0 | Lighter background |
|
||||
| base02 | color8 | Selection background |
|
||||
| base03 | color8 | Comments, invisibles |
|
||||
| base04 | color7 | Dark foreground |
|
||||
| base05 | foreground | Default foreground |
|
||||
| base06 | color15 | Light foreground |
|
||||
| base07 | color15 | Lightest foreground |
|
||||
| base08 | color1 | Red (errors, deletions) |
|
||||
| base09 | color3 | Orange |
|
||||
| base0A | color3 | Yellow (warnings) |
|
||||
| base0B | color2 | Green (success, additions) |
|
||||
| base0C | color6 | Cyan (info) |
|
||||
| base0D | color4 | Blue (primary accent) |
|
||||
| base0E | color5 | Magenta (keywords) |
|
||||
| base0F | color1 | Brown (deprecated) |
|
||||
|
||||
## Step 2: Set the Icon Theme
|
||||
|
||||
Create `icons.theme` with a single line containing the GTK icon theme name:
|
||||
|
||||
```
|
||||
Yaru-blue
|
||||
```
|
||||
|
||||
Common options from the `yaru-theme` package: `Yaru-blue`, `Yaru-purple`, `Yaru-red`, `Yaru-sage`, `Yaru-olive`, `Yaru-magenta`, `Yaru-yellow`, `Yaru-gray`, `Yaru-grey`, `Yaru-wartybrown`.
|
||||
|
||||
## Step 3: Add Backgrounds (Optional)
|
||||
|
||||
Place wallpaper images in a `backgrounds/` directory. Use numbered prefixes to control the default selection order -- the first file alphabetically becomes the default wallpaper.
|
||||
|
||||
```
|
||||
backgrounds/
|
||||
├── 1-main-wallpaper.jpg # Default wallpaper (first alphabetically)
|
||||
├── 2-alternate.png # Additional option
|
||||
└── 3-minimal.jpg # Another option
|
||||
```
|
||||
|
||||
Supported formats: `.jpg`, `.png`, `.jpeg`.
|
||||
|
||||
If no backgrounds are provided, the system falls back to the catppuccin default wallpaper.
|
||||
|
||||
## Step 4: Light Theme (Optional)
|
||||
|
||||
For light themes, create an empty `light.mode` marker file:
|
||||
|
||||
```bash
|
||||
touch themes/palettes/my-theme/light.mode
|
||||
```
|
||||
|
||||
This controls Stylix polarity (`light` vs `dark`) and affects GTK theming, browser color scheme, and other system-wide dark/light detection.
|
||||
|
||||
### Step 5: App-Specific Configs (Optional)
|
||||
|
||||
These theme-specific files are automatically picked up by the respective application modules in `features/apps/<app>/default.nix` during theme switching.
|
||||
|
||||
### `apps/btop.theme`
|
||||
|
||||
A btop color theme file. See existing themes for the format, or generate one from your palette colors.
|
||||
|
||||
### `apps/neovim.lua`
|
||||
|
||||
A lazy.nvim plugin spec for the matching Neovim colorscheme:
|
||||
|
||||
```lua
|
||||
return {
|
||||
{ "sainnhe/everforest" },
|
||||
{
|
||||
"LazyVim/LazyVim",
|
||||
opts = {
|
||||
colorscheme = "everforest",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### `apps/vscode.json`
|
||||
|
||||
VS Code theme extension reference:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Everforest Dark",
|
||||
"extension": "sainnhe.everforest"
|
||||
}
|
||||
```
|
||||
|
||||
### `apps/hyprland.conf`
|
||||
|
||||
Hyprland visual overrides for this theme. This can include custom border colors, gaps, decorations, blur, and animations. The file is sourced after the default settings, so values here override the defaults.
|
||||
|
||||
```conf
|
||||
$activeBorderColor = rgb(d3c6aa)
|
||||
|
||||
general {
|
||||
col.active_border = $activeBorderColor
|
||||
gaps_in = 6
|
||||
gaps_out = 12
|
||||
border_size = 3
|
||||
}
|
||||
|
||||
decoration {
|
||||
rounding = 10
|
||||
blur {
|
||||
enabled = true
|
||||
size = 5
|
||||
passes = 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Step 6: Template Variables
|
||||
|
||||
Nomarchy has a template system that generates app configs from your `colors.toml`. Templates in `themes/templates/*.tpl` use placeholder syntax:
|
||||
|
||||
| Syntax | Example Value | Description |
|
||||
|---------------------|---------------|--------------------------------|
|
||||
| `{{ background }}` | `#2d353b` | Color value as-is (with `#`) |
|
||||
| `{{ background_strip }}` | `2d353b` | Color value without `#` |
|
||||
| `{{ background_rgb }}` | `45,53,59` | Color as decimal RGB |
|
||||
|
||||
Every key from `colors.toml` is available as a template variable. Templates are processed automatically by `nomarchy-theme-set-templates` when switching themes.
|
||||
|
||||
To add custom templates, place `.tpl` files in `~/.config/nomarchy/themed/`. User templates take priority over built-in ones.
|
||||
|
||||
## Step 7: Preview Image (Optional)
|
||||
|
||||
Add a `preview.png` screenshot of the theme in action. This is displayed in the theme selector menu (`nomarchy-menu theme`).
|
||||
|
||||
## Applying Your Theme
|
||||
|
||||
### During development (runtime switch)
|
||||
|
||||
```bash
|
||||
nomarchy-theme-set my-theme
|
||||
```
|
||||
|
||||
This updates `~/.config/nomarchy/state.json`, processes templates, and triggers a Home Manager rebuild.
|
||||
|
||||
### Setting as default (Nix configuration)
|
||||
|
||||
In your `home.nix`:
|
||||
|
||||
```nix
|
||||
{
|
||||
nomarchy.theme = "my-theme";
|
||||
}
|
||||
```
|
||||
|
||||
Then rebuild: `env-update` (or `sys-update` for system-wide changes).
|
||||
|
||||
## Theme Discovery
|
||||
|
||||
The system automatically discovers themes by scanning `themes/palettes/` for directories containing a `colors.toml` file. No registration step is needed -- just create the directory with a valid `colors.toml` and the theme is available.
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] `colors.toml` with all 24 color fields
|
||||
- [ ] `icons.theme` with a valid GTK icon theme name
|
||||
- [ ] `backgrounds/` with at least one numbered wallpaper
|
||||
- [ ] `light.mode` if it's a light theme
|
||||
- [ ] `apps/neovim.lua` with colorscheme plugin spec
|
||||
- [ ] `apps/vscode.json` with theme extension reference
|
||||
- [ ] `apps/btop.theme` with terminal monitor colors
|
||||
- [ ] `apps/hyprland.conf` if custom decorations/animations are desired
|
||||
- [ ] `preview.png` for the theme selector
|
||||
Reference in New Issue
Block a user