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