# 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]                 # text and ink by emphasis
primary = "#d8dee9"
secondary = "#e5e9f0"
muted = "#616e88"

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

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