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.

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.

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.

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 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.

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.