Theme Format

Theme files at ~/.config/otty/themes/<name>.ottytheme are real TOML (unlike the main config). Schema below.

Minimal example

# ~/.config/otty/themes/midnight.ottytheme
[terminal]
foreground = "#e0e0ff"
background = "#0a0a14"
palette = [
  "#0a0a14", "#ff4d6d", "#7be0ad", "#ffd66b",   # 0-3:  black red green yellow
  "#82aaff", "#c792ea", "#89ddff", "#d0d0ff",   # 4-7:  blue magenta cyan white
  "#3b3b50", "#ff6b88", "#9eebbf", "#ffe28a",   # 8-11: bright black red green yellow
  "#a0c0ff", "#daa6f7", "#a8e6ff", "#ffffff",   # 12-15: bright blue magenta cyan white
]

Activate:

theme = midnight

Only [terminal] is required; every other section is optional.

[terminal] — required

Key	Type	Description
foreground	color	Default text colour
background	color	Default background colour
palette	array[16] color	ANSI 0-15
cursor	color	Cursor block (falls back to foreground)
cursor-text	color	Foreground while inside cursor
selection-foreground	color	(legacy — prefer [selection])
selection-background	color	(legacy — prefer [selection])

[ui] — UI chrome

[ui]
title-bar-bg     = "#0e0e18"
tab-bar-bg       = "#0a0a14"
tab-active-bg    = "#1a1a28"
tab-active-fg    = "#ffffff"
sidebar-divider  = "#3b3b50"

Controls the window frame, tab sidebar, command palette tint.

[selection] — selection

[selection]
foreground = "#ffffff"
background = "#3a3a55"

[cursor] — cursor

[cursor]
color = "#ffa830"
style = "beam"      # block | underline | beam
blink = true

[ghost] — autocomplete ghost text

[ghost]
foreground = "#666680"

[window] — backdrop

[window]
material = "glass"         # none | vibrancy-thin | vibrancy-regular |
                           # vibrancy-thick | glass        (macOS names)
                           # none | acrylic-thin | acrylic |
                           # mica | mica-alt               (Windows names)
background = "#2C2C2C"     # the material's own tint, not a fill over it
opacity    = 0.8           # how strongly the tint beats the blurred desktop
radius     = 8

[mac] / [windows] — per-platform materials

macOS blurs with vibrancy and Liquid Glass; Windows blurs with Mica and Acrylic. They are different effects, so a theme can name one per platform:

[window]
material = "glass"         # what every platform falls back to

[mac]
material = "glass"
color    = "#2C2C2C"       # `color` is the short spelling of `background`

[windows]
material = "mica-alt"      # a Windows-only material
opacity  = 0.9

Each of material / color (background) / opacity falls back to [window] on its own, [mac] is ignored on Windows and vice versa, and Linux reads [window]. Note the plural: [window] is the window, [windows] is the operating system.

A material written for the other platform is mapped across rather than dropped — vibrancy-thin↔acrylic-thin, vibrancy-regular↔mica, vibrancy-thick↔mica-alt, glass↔acrylic — so a theme written on macOS still gets a sensible Windows surface.

Only the sidebar

Put the material on [windows.sidebar] (or [mac.sidebar], or the shared [sidebar]) instead, and only the chrome column is translucent: the content column keeps its opaque fill and runs the full height of the window, title strip included — the two-column shape the Windows 11 shell uses.

[windows.sidebar]
material = "acrylic"       # the column is the backdrop…
color    = "#2C2C2C"       # …this is its tint
opacity  = 0.8

Built-in Acrylic Dark and One Light both ship this on Windows.

Inheritance

inherits = "glass-dark"

[terminal]
background = "#000000"     # override only this; everything else from glass-dark

Useful for tweaking a built-in theme without restating all 16 palette entries.

See also

• Themes — choosing and customizing.
• Config File Format — separate from theme format.
• Spec: docs/spec/THEME_SPEC.md in the repo.