# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Build & Test Commands
```bash
cargo build # default features (popular)
cargo build --all-features # all theme families + integrations
cargo check --no-default-features # verify no_std compatibility
cargo test # integration tests (default features)
cargo test --all-features # all tests including base16 feature-gated
cargo test <name> # run a single test by name
cargo clippy --all-targets --all-features # lint (lib + tests + examples)
cargo doc --no-deps # generate docs
```
**Xtask pipeline** (code generation):
```bash
cargo xtask clean [--cache] [--generated] # remove fetched/generated files
cargo xtask check # verify generated files are fresh
cargo xtask ci # fetch → generate → clippy → test
```
After modifying xtask or adding data, run fetch + generate then verify with `cargo build --all-features`.
**dev.sh** (recommended for development):
```bash
./dev.sh ci # full local CI: lint → test → check → freshness → examples
./dev.sh lint --all # fmt + clippy (lib + xtask) + doc build
./dev.sh lint --fix --all # auto-fix lint issues
./dev.sh test --all # test with --all-features
./dev.sh examples --all # run all examples
./dev.sh check # feature isolation (each feature compiles alone)
./dev.sh doctor # check prerequisites
./dev.sh snapshots review # review pending insta snapshots
./dev.sh xtask check # verify generated files are fresh
```
## Architecture
**`no_std` library** using `#![no_std]` + `extern crate alloc`. Uses `libm::pow` for WCAG luminance math instead of `std::f64::powf`. Methods returning `String` or `Vec` use `alloc`.
**Core types** (`src/types.rs`): `Color` (RGB u8), `Theme` (29 color fields + 4 metadata fields), `Variant` (Dark/Light), `Contrast` (High/Normal/Low based on WCAG ratio thresholds: >=10.0, >=4.5, <4.5).
**Theme discovery** (`src/iter.rs`): `collect_all_themes()` aggregates themes from all enabled feature modules. For zero-allocation access, use module-level `THEMES` slices directly (e.g., `popular::THEMES`).
### Two kinds of themes
- **Popular** (`src/popular/*.rs`): Hand-crafted `const Theme` definitions with accurate colors from official sources. One file per family (e.g., `catppuccin.rs` has LATTE/FRAPPE/MACCHIATO/MOCHA). 24 family files, 49 themes total.
- **Generated** (`src/base16/*.rs`, `src/base24/*.rs`, `src/vim/*.rs`, `src/emacs/*.rs`): Auto-generated by `cargo xtask generate` from upstream data. 305 base16 + 184 base24 + 464 vim + 102 emacs = 1055 generated themes. **Do not edit these files** — modify the corresponding module in `xtask/src/generate/` instead.
### Feature gates
Theme modules: `popular` (default), `base16`, `base24`, `vim`, `emacs`, `all`.
Framework integrations: `bevy-color-integration`, `colored-integration`, `comfy-table-integration`, `crossterm-integration`, `cursive-integration`, `egui-integration`, `iced-integration`, `image-integration`, `macroquad-integration`, `owo-colors-integration`, `palette-integration`, `plotters-integration`, `ratatui-integration`, `slint-integration`, `syntect-integration`, `termion-integration`, `tiny-skia-integration`, `wgpu-integration`.
Each integration module in `src/integration/` provides `From<Color>` for the framework's color type. Some also provide convenience methods on `Theme` (e.g., `to_syntect_theme_settings()`, `apply_to_cursive_palette()`, `plotters_series_colors()`, `colorize()`, `style_comfy_cell()`).
### Data pipeline
`data/` is gitignored. Upstream data (YAML schemes, .vim files, .el files) is fetched on demand by `cargo xtask fetch`, then `cargo xtask generate` produces sorted, deterministic `.rs` files with WCAG contrast classification. The generated `src/{base16,base24,vim,emacs}/` files ARE committed (Strategy B — no build-time parsing for consumers). There is no `build.rs` — all code generation happens via xtask, not at build time.
## Conventions
- Edition 2024, GPL-3.0 license
- `#![forbid(unsafe_code)]`, `#![deny(clippy::unwrap_used)]` — use `.expect()` in library code
- All public items must have `///` doc comments; modules must have `//!` docs
- Popular theme contrast values must match WCAG calculation (validated by `contrast_field_matches_calculation` test)
- Theme doc comments include `/// Contrast: {High|Normal|Low}` matching the actual enum value
- CI runs tests with `--test-threads=1` (sequential)