diff --git a/README.md b/README.md
index a6a6cbf..a613844 100644
--- a/README.md
+++ b/README.md
@@ -242,6 +242,46 @@ since the GUI's child host/viewer processes inherit it; the `--gui --relay`
 flag form is forwarded to them too. Both ends must use the same relay to
 find each other.
 
+## Themes
+
+The `--gui` front-end ships three colour themes — **Default Dark**,
+**Catppuccin Mocha**, and **Catppuccin Latte** — and you can add your own.
+Pick one under **Settings → Appearance**; the choice is remembered.
+
+A theme is a small TOML file of named colours:
+
+```toml
+name = "My Theme"
+dark = true            # base egui defaults to start from (dark or light)
+
+window_bg = "#1b1b1f"  # window background
+panel_bg = "#242429"   # panels / frames
+input_bg = "#141417"   # text fields, the ticket box
+text = "#e6e6ea"       # primary text
+weak_text = "#a0a0a8"  # hints, secondary text
+accent = "#5aa0f2"     # selection, links, the active control
+button_bg = "#33333a"  # buttons at rest
+button_hovered = "#44444d"
+streaming = "#6fdc8c"  # "● Streaming"
+waiting = "#f2c14e"    # "● Waiting for viewers…"
+success = "#6fdc8c"    # "✓ Copied", valid-code confirmation
+warning = "#f0a85a"    # non-fatal warnings
+error = "#f2756f"      # errors
+```
+
+Colours are `#rrggbb` hex strings. Any field you leave out falls back to
+Default Dark, so partial files are fine.
+
+Two ways to make one:
+
+- **In the app:** Settings → Appearance → *Edit / create a theme* gives you a
+  colour picker per field with a live preview, and **Save** writes a `.toml`.
+- **By hand:** drop a `.toml` into `~/.config/pixelpass/themes/` (the XDG
+  config dir). It appears in the picker next time you open Settings.
+
+Sharing a theme is just sending someone the file. A user theme whose `name`
+matches a built-in overrides that built-in.
+
 ## Audio
 
 By default pixelpass captures the default sink's monitor — the viewer