52 lines
1.8 KiB
Markdown
52 lines
1.8 KiB
Markdown
# Themes — Authoring Guide
|
|
|
|
## File Layout
|
|
|
|
- Global themes: `themes.toml` (single multi-theme file) OR `themes/<name>.toml` (one file per theme)
|
|
- Project-specific overrides: `<project>/project_themes.toml`
|
|
|
|
Both layouts are scanned and merged; project themes with the same name as a global theme override it.
|
|
|
|
Override the global path via the `SLOP_GLOBAL_THEMES` env var.
|
|
|
|
## Schema
|
|
|
|
```toml
|
|
# human-readable label
|
|
description = "Solarized Dark by Ethan Schoonover"
|
|
|
|
# one of: dark | light | mariana | retro_blue
|
|
# selects which built-in imgui_color_text_edit palette to apply
|
|
syntax_palette = "dark"
|
|
|
|
[colors]
|
|
# RGB triples, 0-255
|
|
window_bg = [ 0, 43, 54]
|
|
text = [147, 161, 161]
|
|
button_hovered = [ 38, 139, 210]
|
|
# ... any imgui.Col_ key is accepted
|
|
```
|
|
|
|
`[colors]` is required. Missing required section is a hard error (logged to stderr, theme skipped).
|
|
|
|
## Available Color Keys
|
|
|
|
All keys are imgui `Col_` enum members in snake_case. The loader does best-effort mapping; unknown keys are silently ignored. Common ones: `window_bg`, `child_bg`, `popup_bg`, `border`, `frame_bg`, `title_bg`, `menu_bar_bg`, `scrollbar_bg`, `button`, `header`, `separator`, `tab`, `text`, `text_disabled`, `check_mark`, `slider_grab`, `table_header_bg`.
|
|
|
|
## Syntax Palette Mapping
|
|
|
|
`imgui-bundle` ships four built-in `imgui_color_text_edit` palettes and exposes no API to define new ones. We pick the closest match per theme:
|
|
|
|
| UI Theme | Syntax Palette |
|
|
|---|---|
|
|
| Solarized Dark | `dark` |
|
|
| Solarized Light | `light` |
|
|
| Gruvbox Dark | `retro_blue` |
|
|
| Moss | `mariana` |
|
|
| (anything else) | `dark` |
|
|
|
|
You can override the mapping per theme by setting the `syntax_palette` field in the TOML.
|
|
|
|
## Hot Reload
|
|
|
|
Theme TOMLs are loaded once at module init. To pick up a new file, call `theme.load_themes_from_disk()` (or restart the app). |