apex/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build

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.