Colors and Themes

Colors and Themes

Beez can colorize terminal output using ANSI escape codes. Colors apply to progress lines, summaries, worker prefixes, and status text.

Basic switches

ui = {
    colors = true,
    truecolor = true,
    icons = true,
}

Key	Default	Effect
colors	true	Enable ANSI colors. When false, output is plain text.
truecolor	follows colors when unset	Use 24-bit RGB hex colors when supported. When false, map to 16-color ANSI.
icons	true	Use Unicode icons in summaries and some spinners. When false, text alternatives are used.

Built-in default palette

When colors = true and no theme is set, Beez uses an internal default palette (neutral grays with green success and blue info accents).

Named themes

Define palettes under themes, then select one with theme:

ui = {
    colors = true,
    theme = "gruvbox",
    themes = {
        gruvbox = {
            text = "#ebdbb2",
            muted = "#928374",
            success = "#b8bb26",
            warning = "#fabd2f",
            error = "#fb4934",
            info = "#83a598",
            accent = "#fe8019",
            progress_fill = "#b8bb26",
            progress_empty = "#665c54",
            cache_hit = "#8ec07c",
            worker_prefix = "#83a598",
        },
    },
}

If theme names an entry that does not exist in themes, Beez fails when UI settings are resolved at run time (or during --show-config) with unknown ui theme: .... build.lua can still load; the error appears when Beez applies the theme.

Palette keys

Key	Typical use
text	Progress detail, body text
muted	De-emphasized labels
success	Success status, compact summary title
warning	Warnings
error	Errors, failed status
info	Informational accents
accent	Progress category (non-cache)
progress_fill	Filled portion of progress bars
progress_empty	Empty portion of progress bars
cache_hit	Cached step category, time-saved hints
worker_prefix	Worker label in verbose output

Themes from global and project config merge by name: later layers override individual theme tables.

Where colors appear

UI element	Palette keys
Progress category (running)	accent
Progress category (cached)	cache_hit
Progress detail	text
Progress bar fill	progress_fill
Worker prefix (ui.prefix)	worker_prefix
Simple summary check/cross	icons + success / error via formatting
Compact summary box	success, error, info, cache_hit, muted
Minimal "saved time" line	cache_hit

Icons

When icons = true:

• Simple summary uses ✓ / ✗ prefixes.
• Data summary segment status uses ✓ PASS / ✗ FAIL.
• Spinner indicator dots uses Braille animation frames (not the default; default progress indicator is step).

When icons = false, summaries use PASS / FAIL text and the dots spinner falls back to minimal (see Progress and Animation).

Related pages

• Progress and Animation - progress bars and spinners
• Run Summaries - colored end-of-run messages
• Output Modes - verbose worker prefix coloring
• Config Reference - all ui.* keys