34 lines
2.0 KiB
Markdown
34 lines
2.0 KiB
Markdown
# 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.
|