# Themes
The 31 theme files this crate ships. Consumers get them two ways: as a
directory via `bundled_themes_dir()`, or embedded with no path at all via
`embedded_themes()`.
Attribution for the adapted palettes lives in
[THIRD-PARTY-NOTICES.md](../THIRD-PARTY-NOTICES.md). Each adapted file also
carries its upstream, license, and copyright line in a header comment, so the
credit travels with the file if someone copies one out on its own.
## File format
A theme declares colors by intent, not by hue. Sections:
```toml
[meta]
name = "Nord" # display name; falls back to the filename
variant = "dark" # "dark", "light", or "high-contrast"
[surface] # container backgrounds by elevation
page = "#2e3440"
raised = "#3b4252"
sunken = "#434c5e"
overlay = "#3b4252"
[content] # the ink
primary = "#d8dee9"
[action] # interactive / brand color
primary = "#81a1c1"
[status] # state semantics
danger = "#bf616a"
success = "#a3be8c"
warning = "#ebcb8b"
info = "#88c0d0"
[line]
border = "#4c566a"
[category] # optional; tag and label colors
```
Interactive states (hover, active, selection, row striping, contrast pairings)
are not authored. `resolve()` derives them perceptually in OKLab, so a theme
file stays small and every consuming app derives them identically.
Neither are the ink's emphasis steps. `content-secondary` and `content-muted`
are `content.primary` moved 12% and 42% of the way toward `surface.page`, and a
value written under those keys is overwritten at load. They were authored until
2026-08-16, and separately-authored steps drift: three of the themes here had
ended up with a `secondary` that was lighter than their own `primary`, inverting
the emphasis order every renderer reads. What a theme controls is its ink and
its page; how far back the quieter tones sit is one rule, in one place.
### Theme ID
The filename without `.toml`. IDs may contain only alphanumeric characters,
hyphens, and underscores; path traversal characters are rejected.
## Adding a theme
1. Create `your-theme.toml` here.
2. If it adapts an existing palette, add the header comment naming the upstream
project, its license, and the exact copyright line from its LICENSE file.
Verify against the actual LICENSE, not a README or a secondhand claim.
3. Add a row to [THIRD-PARTY-NOTICES.md](../THIRD-PARTY-NOTICES.md).
4. Run `cargo test`. The suite fails if a theme is missing from the notices
file, if an adapted theme has no inline attribution, or if the embedded set
drifts from this directory.
Original themes (no third-party palette) skip steps 2 and 3, but must be listed
under "Original themes" in the notices file.
## License
The theme files are MIT, as is the rest of the crate. The underlying palettes
of adapted themes remain their original authors' work; see
[THIRD-PARTY-NOTICES.md](../THIRD-PARTY-NOTICES.md).