Themes

The TUI is colored by semantic roles, not raw hexes. Every render site resolves a role (accent, text_primary, selection_bg, …) through the active theme, so one switch restyles the whole interface at runtime. A theme is one file, 43 keys, done.

Switching themes

To pin a theme without the picker, set it in config.toml:

[tui]
theme = "nord"

The value is applied at boot before the first frame. An empty or unknown name falls back to crab-dark. User theme files are re-scanned on every /theme invocation, so editing a preset file hot-loads it without restarting the TUI.

Built-in themes

There are 39 built-in themes: 8 hand-tuned presets plus a curated pack of 31 converted from popular upstream palettes (see Imported themes). crab-dark is the default and matches the historical OpenCrabs look.

The curated pack adds: aura, ayu, carbonfox, catppuccin-frappe, catppuccin-macchiato, cobalt2, cursor, everforest, flexoki, github, gruvbox, gruvbox-light, kanagawa, material, matrix, mercury, nightowl, nord, one-dark, opencode, orng, osaka-jade, palenight, rosepine, rosepine-dawn, synthwave84, tokyonight, tokyonight-storm, vercel, vesper, zenburn.

Gallery

Swatches show four anchor roles per theme (accent, body text, success, ink background), read from the shipped sources. Regenerate with python3 docs/scripts/gen_theme_gallery.py.

The 43 roles

A user theme is a flat TOML file mapping every role to a #RRGGBB hex. Role names double as the TOML keys. What each one colors:

Decorative animation cycles (like the rotating project badge colors) are deliberately not roles: they stay preset-agnostic.

Writing your own theme

Drop a file at ~/.opencrabs/themes/<name>.toml. The file stem is the theme name. All 43 keys are required; here is a complete valid theme (nord, from the curated pack):

accent = "#8fbcbb"
accent_teal = "#8fbcbb"
accent_soft = "#eceff4"
text_primary = "#eceff4"
text_secondary = "#8b95a7"
text_muted = "#767b84"
text_dim = "#9ca0a8"
gray = "#434c5e"
gray_mid = "#9ca0a8"
gray_detail = "#91959e"
gray_dim = "#7e838c"
gray_dark = "#6b707a"
gray_base = "#434c5e"
gray_light = "#d0d3d9"
gray_soft = "#afb3ba"
gray_muted = "#8d929a"
success = "#a3be8c"
analytics_green = "#a3be8c"
green_check = "#a3be8c"
error = "#bf616a"
error_soft = "#bf616a"
error_faded = "#6f4853"
warning = "#d08770"
warning_muted = "#9f6e62"
amber_muted = "#87625a"
teal_vivid = "#8fbcbb"
teal_bright = "#8fbcbb"
teal_muted = "#6d8c90"
teal_calm = "#5a7177"
blue_slate = "#698f9e"
blue_steel = "#88c0d0"
blue_link = "#81a1c1"
blue_sky = "#88c0d0"
blue_soft = "#648896"
blue_vivid = "#88c0d0"
blue_code = "#88c0d0"
selection_bg = "#505660"
surface_panel = "#3b4252"
surface_qr = "#343a45"
surface_code = "#434c5e"
surface_code_alt = "#494e59"
ink = "#2e3440"
purple_soft = "#81a1c1"

Validation rules

Validation is loud, never silent. A theme file is rejected, with the reason shown by /theme list, when it:

1. misses any of the 43 roles — the error names the missing key;
2. carries an unknown key — strict typo guard, there is no partial-schema mode;
3. uses a malformed value — only #RRGGBB or RRGGBB, case-insensitive;
4. fails the contrast floor — eight reading-critical (foreground, background) pairs must hit 2.5:1 WCAG contrast: text_primary/text_secondary/accent/success/error/ warning on ink, blue_code on surface_code, and gray_mid on surface_panel. Deliberately dim tiers (text_muted, text_dim, …) are excluded — dim is their job;
5. collides with a built-in name — user files can never shadow a shipped preset.

Everything else is free for the runtime: each valid theme gets its ANSI-256 fallback tier derived automatically, so terminals without truecolor still render it (nearest index in the 6×6×6 cube, grayscale ramp for neutrals).

Theme enforcement (v0.5.3)

Every widget in the TUI now resolves its colours through the theme engine — the last hardcoded ANSI sites are gone, and a suite-level guard fails the build if a new raw ANSI colour site appears (#1634). Themes can also declare an optional canvas background (the source background carries through catalog conversion), so a theme can restyle the whole terminal canvas, not just the widgets on it.

Imported themes

The 31-theme curated pack was generated by the in-tree converter (tui::theme_catalog) from two upstream formats:

• alacritty-theme TOML ([colors.primary] background/foreground plus the 16 ANSI colors) — the alacritty/alacritty-theme catalog, 176 themes;
• opencode theme JSON (defs + theme token maps with dark/light variants, hex strings, ANSI integers, defs references and "none") — the sst/opencode built-in themes, 33 assets.

Both convert through a fixed 43-role mapping (semantic token first, ANSI color or deterministic bg/fg mix as fallback), and every generated file is pre-certified by the same validator user themes face — a converted file that doesn’t validate never ships. Each pack file carries a # source: provenance header naming the upstream repo, file, and fetch date; the gallery table shows it. Upstream palettes belong to their authors; the pack imports their colors, not their names’ goodwill.

The converter is generation-time tooling: the TUI itself only knows the embedded presets and your drop-in files.