Beta·every release is a pre-releaseAPIs and harness behavior are still changing·every release until v1 is a pre-release
uzev1 beta
Reference

Themes

A theme file, what it may leave out, and the ways to write a colour

A theme is a JSON file in ~/.uze/themes/; its file name is its id. Anything it leaves out comes from the built-in default, so a whole light theme is a few lines:

~/.uze/themes/dawn.json
{
  "name": "dawn",
  "colors": {
    "surface.background": "#faf7f2",
    "text.primary": "#2b2a28",
    "text.muted": "#7b736a",
    "accent": "#2f7d4f"
  }
}

Every surface, border and diff tint is derived from the background you declare.

Besides colors and symbols, a theme may carry a description and a syntax block naming the palette code is highlighted with, one of InspiredGitHub, Solarized (dark), Solarized (light), base16-eighties.dark, base16-mocha.dark, base16-ocean.dark or base16-ocean.light: "syntax": { "theme": "base16-ocean.light" }. Any other key is an error.

uze config theme set dawn
uze config theme show        # what resolved, from which layer, and any warnings

Point your editor at theme.schema.json for completion over every token and symbol.

A variation of another theme

{
  "extends": "dracula",
  "name": "Dracula Soft",
  "colors": { "surface.background": "#343746" }
}

What the parent derived from its background is recomputed against yours. A file named after a built-in theme, like dracula.json, replaces it.

The built-in themes are dark, which every theme completes from, light, dracula, catppuccin-mocha, tokyo-night and tokyo-night-light. Until you choose one, uze draws in adaptive: light while your system is light and dark while it is dark (uze config theme set adaptive --light <id> --dark <id> picks the pair). adaptive is a selection, not a file, so a theme cannot take that name.

Writing a colour

FormMeans
#rrggbbExactly this colour
#rrggbbaaThis colour at that alpha, over the background
~aaSet apart from the background by that much, in whichever direction is visible
@tokenWhatever that token is
@token/aaThat token at that alpha, over the background

~aa is what makes one theme work light or dark: a raised surface is a little lighter on a dark background and a little darker on a light one. surface.background itself must be an opaque #rrggbb.

Symbols

Every mark uze draws is a named symbol a theme can replace, with a string, a list of animation frames, or an object with an explicit width. To change a single glyph without writing a theme, write it in ~/.uze/config.toml, under [appearance.symbols], [appearance.colors] or [appearance.syntax]: the same fields as a theme file, applied last, over whatever theme and icon set you use.

[appearance.symbols]
"status.idle" = ""

[appearance.colors]
accent = "#bd93f9"

What a theme reaches

The workspace, management and the CLI's own output, and also what a program in a pane is told the terminal's colours are, so an agent picks the light or dark UI you are actually looking at. It never changes layout.

A colour with poor contrast against the background is reported by uze config theme show, never corrected. A theme that fails to load says why on every run, and uze draws with the default until it is fixed.

On this page