54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Build
|
||
|
||
```bash
|
||
uv run build.py
|
||
```
|
||
|
||
Regenerates all theme files from `src/*.yaml` via Jinja2 templates into `dist/`. There is no watch mode — rerun after any YAML or template change. Python 3.12+ required; dependencies managed via `uv` (`pyproject.toml`).
|
||
|
||
## Architecture
|
||
|
||
Apex is a **theme factory** — a build system that generates native theme configs for 18 applications from a single semantic color specification.
|
||
|
||
**Data flow:**
|
||
1. `src/neon.yaml` and `src/aeon.yaml` define the canonical color palette and semantic roles
|
||
2. `templates/<app>/*.j2` define per-application output formats (Lua, JSON, TOML, CSS, Conf, etc.)
|
||
3. `templates/<app>/meta.yaml` controls the build strategy:
|
||
- `strategy: individual` → outputs `apex-neon.<ext>` and `apex-aeon.<ext>` separately
|
||
- `strategy: aggregated` → outputs a single file containing both schemes (e.g., `apex.json` for Zed)
|
||
4. `build.py` orchestrates rendering; `dist/` holds all generated artifacts (gitignored)
|
||
|
||
**Adding a new app target:** create `templates/<app>/`, add a `meta.yaml` with strategy, write `.j2` templates using the YAML variables, then run the build.
|
||
|
||
## Theme Design Rules
|
||
|
||
`GEMINI.md` is the authoritative source of truth for color semantics. Key axioms:
|
||
|
||
- **Red (`#ff0044`) = Active Intent** — cursor, current location, selection, critical errors. Text on red backgrounds must be `#050505` (Neon) or `#0a0a0a` (Aeon).
|
||
- **Cyan = Informational** — never use for errors or destruction.
|
||
- **Purple = Sacred** — reserved for root access and exceptional system states.
|
||
- **Bright ANSI variants (8–15)** are for escalated/active states only.
|
||
- Do not introduce colors without a semantic reason. If it has no signal purpose, remove it.
|
||
|
||
Before modifying `src/*.yaml`, consult `GEMINI.md` to verify that any new or changed role fits the semantic palette.
|
||
|
||
## Conventions
|
||
|
||
- Commit style: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`)
|
||
- Template output names: `apex-<scheme>.<ext>` for individual; base name for aggregated
|
||
- YAML keys in `src/`: keep consistent with existing semantic roles; add new roles only when truly necessary
|
||
- `dist/` is build output — never edit by hand
|
||
|
||
## Validation
|
||
|
||
After changes, run `uv run build.py` and inspect relevant files in `dist/`. For Neovim-specific validation, `scripts/nvim-audit.sh` is available.
|
||
|
||
## Scripts
|
||
|
||
- `scripts/release.sh` — Per-app versioning and Gitea release automation. Usage: `bash scripts/release.sh <semver>`. Discovers changed apps via git diff, updates `meta.yaml` version fields, builds, and publishes tarballs. Supports `--dry-run`.
|
||
- `scripts/nvim-audit.sh` — Validates the built Neovim theme by running headless Neovim. Requires `dist/nvim/colors/apex-neon.lua` to exist first.
|