| 1 |
# Themes |
| 2 |
|
| 3 |
The 31 theme files this crate ships. Consumers get them two ways: as a |
| 4 |
directory via `bundled_themes_dir()`, or embedded with no path at all via |
| 5 |
`embedded_themes()`. |
| 6 |
|
| 7 |
Attribution for the adapted palettes lives in |
| 8 |
[THIRD-PARTY-NOTICES.md](../THIRD-PARTY-NOTICES.md). Each adapted file also |
| 9 |
carries its upstream, license, and copyright line in a header comment, so the |
| 10 |
credit travels with the file if someone copies one out on its own. |
| 11 |
|
| 12 |
## File format |
| 13 |
|
| 14 |
A theme declares colors by intent, not by hue. Sections: |
| 15 |
|
| 16 |
```toml |
| 17 |
[meta] |
| 18 |
name = "Nord" # display name; falls back to the filename |
| 19 |
variant = "dark" # "dark", "light", or "high-contrast" |
| 20 |
|
| 21 |
[surface] # container backgrounds by elevation |
| 22 |
page = "#2e3440" |
| 23 |
raised = "#3b4252" |
| 24 |
sunken = "#434c5e" |
| 25 |
overlay = "#3b4252" |
| 26 |
|
| 27 |
[content] # the ink |
| 28 |
primary = "#d8dee9" |
| 29 |
|
| 30 |
[action] # interactive / brand color |
| 31 |
primary = "#81a1c1" |
| 32 |
|
| 33 |
[status] # state semantics |
| 34 |
danger = "#bf616a" |
| 35 |
success = "#a3be8c" |
| 36 |
warning = "#ebcb8b" |
| 37 |
info = "#88c0d0" |
| 38 |
|
| 39 |
[line] |
| 40 |
border = "#4c566a" |
| 41 |
|
| 42 |
[category] # optional; tag and label colors |
| 43 |
``` |
| 44 |
|
| 45 |
Interactive states (hover, active, selection, row striping, contrast pairings) |
| 46 |
are not authored. `resolve()` derives them perceptually in OKLab, so a theme |
| 47 |
file stays small and every consuming app derives them identically. |
| 48 |
|
| 49 |
Neither are the ink's emphasis steps. `content-secondary` and `content-muted` |
| 50 |
are `content.primary` moved 12% and 42% of the way toward `surface.page`, and a |
| 51 |
value written under those keys is overwritten at load. Separately-authored |
| 52 |
steps drift out of order, so a `secondary` ends up lighter than its own |
| 53 |
`primary` and inverts the emphasis order every renderer reads. What a theme |
| 54 |
controls is its ink and its page; how far back the quieter tones sit is one |
| 55 |
rule, in one place. |
| 56 |
|
| 57 |
### Theme ID |
| 58 |
|
| 59 |
The filename without `.toml`. IDs may contain only alphanumeric characters, |
| 60 |
hyphens, and underscores; path traversal characters are rejected. |
| 61 |
|
| 62 |
## Adding a theme |
| 63 |
|
| 64 |
1. Create `your-theme.toml` here. |
| 65 |
2. If it adapts an existing palette, add the header comment naming the upstream |
| 66 |
project, its license, and the exact copyright line from its LICENSE file. |
| 67 |
Verify against the actual LICENSE, not a README or a secondhand claim. |
| 68 |
3. Add a row to [THIRD-PARTY-NOTICES.md](../THIRD-PARTY-NOTICES.md). |
| 69 |
4. Run `cargo test`. The suite fails if a theme is missing from the notices |
| 70 |
file, if an adapted theme has no inline attribution, or if the embedded set |
| 71 |
drifts from this directory. |
| 72 |
|
| 73 |
Original themes (no third-party palette) skip steps 2 and 3, but must be listed |
| 74 |
under "Original themes" in the notices file. |
| 75 |
|
| 76 |
## License |
| 77 |
|
| 78 |
The theme files are MIT, as is the rest of the crate. The underlying palettes |
| 79 |
of adapted themes remain their original authors' work; see |
| 80 |
[THIRD-PARTY-NOTICES.md](../THIRD-PARTY-NOTICES.md). |
| 81 |
|