Provider-based theme definition (litmus-knrz)


Status	Done · `archived`
Type	Epic
Priority	normal
Subtasks	Update litmus-cli to load new theme format (litmus-dv2l)
	Remove old Theme struct and hand-curated color sections (litmus-i4kf)
	Add ThemeDefinition and ProviderColors types to litmus-model (litmus-jmna)
	Convert existing themes to ThemeDefinition format (litmus-o4w9)
	Vendor provider theme data (kitty-themes, wezterm color schemes) (litmus-vkne)
	Update litmus-web to provider-scoped theme rendering (litmus-y6dc)
	Build litmus extract-colors command (litmus-z20l)

Goal

Flip the theme model from hand-curated RGB colors to provider-first definitions. Themes are defined as provider → theme name mappings. Colors are extracted from vendored provider theme data at build time, per provider. Simulated scenes, contrast validation, and screenshots are all scoped to a provider.

Priorities: Accuracy (provider colors are source of truth) > Simplicity (minimal authored data) > Coverage (start with popular built-in themes from kitty/wezterm)

Design

Data Model

ThemeDefinition (authored): name, variant (dark/light), providers map (slug → provider theme name)
ProviderColors (generated per-provider): provider slug, source_version, all 22 color fields
No single ResolvedTheme — everything is per-provider

File Layout

themes/gruvbox/
  gruvbox-dark.toml              # authored: name, variant, provider mappings
  gruvbox-dark.kitty.toml        # generated: colors extracted from kitty
  gruvbox-dark.wezterm.toml      # generated: colors extracted from wezterm

Authored file format

name = "Gruvbox Dark"
variant = "dark"

[providers]
kitty = "Gruvbox Dark"
wezterm = "Gruvbox Dark (Gogh)"

Generated file format (e.g. gruvbox-dark.kitty.toml)

# AUTO-GENERATED by litmus extract-colors — do not edit
provider = "kitty"
source_version = "0.37.0"

[colors]
background = "#282828"
foreground = "#ebdbb2"
cursor = "#ebdbb2"
selection_background = "#ebdbb2"
selection_foreground = "#282828"

[colors.ansi]
black = "#282828"
red = "#cc241d"
# ... remaining 14 colors

Extraction Pipeline

Vendored theme data in vendor/ (kitty-themes, wezterm-colorschemes — git subtree or submodule)
Command: litmus extract-colors [--provider kitty] [--theme gruvbox-dark]
Reads ThemeDefinition, looks up provider theme name in vendored data, parses native format, writes per-provider color files
Reuses existing parsers (kitty.rs, base16.rs)

Web App

load_embedded_themes() returns Vec + map of (theme_slug, provider_slug) → ProviderColors
Theme only listed if it has ≥1 ProviderColors file
Provider selector switches both screenshots AND simulated scenes
Contrast validation scoped to selected provider
Theme list cards show available provider badges

CLI

Loads ThemeDefinition + picks one ProviderColors (first available or –provider flag)

Subtasks (in dependency order)

Unblocked (can start in parallel):

litmus-jmna — Add ThemeDefinition + ProviderColors types to litmus-model
litmus-vkne — Vendor provider theme data (kitty-themes, wezterm color schemes)

Blocked by 1 + 2: 3. litmus-z20l — Build litmus extract-colors command

Blocked by 3: 4. litmus-o4w9 — Convert existing themes to ThemeDefinition format

Blocked by 1 + 4 (can run in parallel): 5. litmus-y6dc — Update litmus-web to provider-scoped theme rendering 6. litmus-dv2l — Update litmus-cli to load new theme format

Blocked by 5 + 6: 7. litmus-i4kf — Remove old Theme struct and hand-curated color sections

Summary of Changes

All 7 subtasks completed. Themes are now defined as ThemeDefinition (metadata + base16 colors) + ProviderColors (per-provider ANSI palette extraction). The extract-colors CLI command extracts colors from vendored provider theme data (kitty-themes, wezterm schemes). Both litmus-cli and litmus-web render themes using provider-scoped colors with a global provider selector.

Keyboard shortcuts

Litmus