Themes

A theme is a YAML file that controls the colors and text styles the Polytoken TUI uses. Every color in the TUI comes from a design token, and a theme file assigns a value to each token. Polytoken ships with a built-in default theme, and you can write your own.

Two config keys work together: tui.theme controls whether Polytoken renders in dark or light mode (or detects from your terminal), and tui.theme-file controls which theme file Polytoken loads. The mode determines which palette section (dark: or light:) Polytoken reads from the theme file. When you leave tui.theme-file unset, Polytoken uses the built-in default.

For the full list of tokens and their default values, see Theme Token Reference.

Theme file format

For example, a minimal theme file looks like this:

version: 1
title: My Custom Theme
dark:
  body:
    fg:
      rgb: "#dcdcdc"
  app_background:
    bg:
      rgb: "#000000"
  accent:
    fg:
      rgb: "#78c8ff"
    b: true
light:
  body:
    fg:
      rgb: "#1e1e1e"
  app_background:
    bg:
      rgb: "#ffffff"

The top-level keys:

• version: 1: the schema version. Always 1.
• title:: the display name shown by polytoken theme list.
• dark:: the dark-mode palette.
• light:: the light-mode palette.
• palette:: optional reusable color definitions you reference with $ref.

Every theme file must include both dark: and light:. Each contains token entries. A token entry sets foreground color, background color, and text modifiers.

Token entries

Each token under dark: or light: accepts these fields:

• fg:: foreground color.
• bg:: background color. Same shape as fg:.
• b: true: bold.
• i: true: italic.
• u: true: underline.
• s: true: strikethrough.

Color values accept three formats:

• Hex string: rgb: "#78c8ff"
• RGB triple: rgb: [120, 200, 255] (bytes 0 to 255, or floats 0.0 to 1.0 if any value has a decimal point)
• HSV triple: hsv: [210, 0.531, 1.0] (hue 0 to 360 degrees, saturation and value 0.0 to 1.0)

For example, to set a blue foreground, write fg: { rgb: "#64b4ff" } or use the indented form:

link:
  fg:
    rgb: "#64b4ff"
  u: true

Required tokens

Two tokens must appear in every palette section: body and app_background. The body token provides the default foreground color, and app_background provides the default background color. Any token that omits a foreground inherits from body, and any token that omits a background inherits from app_background.

Reusable definitions

When several tokens share the same color, define the color once under palette: and reference the color with $ref. A $ref points to a same-file fragment using JSON Pointer syntax (#/palette/name):

palette:
  accent_blue:
    rgb: "#64b4ff"
dark:
  link:
    fg:
      $ref: "#/palette/accent_blue"
    u: true

A $ref object must stand alone: it cannot carry sibling keys in the same map. Put the $ref on the color entry (fg: or bg:) and apply any text modifiers at the token level.

A $ref must point to a target that exists in the same file. Polytoken does not support cross-file references or URL references. Circular references produce an error.

How to create a custom theme

1. Copy the built-in default as a starting point:

   polytoken vfs cat polytoken://themes/default.yaml > ~/.config/polytoken/themes/my-theme.yaml

   The path above is the default location. Polytoken stores user config under $XDG_CONFIG_HOME/polytoken (default: ~/.config/polytoken), the same on every platform. If you set XDG_CONFIG_HOME, substitute that directory in the command above.

2. Edit the color values. Change the fg, bg, and modifier entries under dark: and light: to match your palette.

3. Validate the file:

   polytoken theme validate ~/.config/polytoken/themes/my-theme.yaml

   The command reports errors and warnings. Fix any errors before proceeding.

4. Preview the theme at runtime with the /theme slash command in the TUI. See Switching themes at runtime.

5. Set the theme as your default by adding tui.theme-file: my-theme to your config file. The value is the file name without the .yaml extension.

Discovery paths

Polytoken discovers theme files from two locations:

• Built-in VFS: polytoken://themes/ ships with Polytoken.
• User config directory: the themes/ subdirectory under $XDG_CONFIG_HOME/polytoken/ (the same directory that holds config.json5).

Both built-in and user themes appear in discovery. Themes use fully qualified file names, so a user theme and a built-in theme never collide or shadow each other.

The polytoken theme list command shows every discovered theme with its source and validity status:

polytoken theme list

NAME              SOURCE     VALID  TITLE
boringcyberpunk   built-in   ✓      Boring Cyberpunk
default           built-in   ✓      Polytoken Default
rose-pine         built-in   ✓      Rose Pine

tui.theme versus tui.theme-file

These two config keys are independent dimensions:

• tui.theme (auto, light, or dark) controls which palette section Polytoken uses. When you set tui.theme to auto, Polytoken detects the terminal background and picks dark or light.
• tui.theme-file (optional) controls which theme file Polytoken loads. When you leave tui.theme-file unset, Polytoken uses the built-in default.

For example, with tui.theme: dark and tui.theme-file: solarized, Polytoken loads the dark: section from a file named solarized.yaml. Changing tui.theme to light switches to the light: section of the same file, without changing the theme file.

CLI commands

List discovered themes

polytoken theme list

Shows every discovered theme with its name, source, validity status, and title. Add --format json for machine-readable output.

Show the token catalog

polytoken theme tokens

Shows every design token with its category, required status, and resolved dark and light default styles. Pass --format json for structured output.

Validate theme files

polytoken theme validate

Run without arguments to validate the built-in default theme. Pass a path or a polytoken:// URI to validate a specific file:

polytoken theme validate ~/.config/polytoken/themes/my-theme.yaml
polytoken theme validate polytoken://themes/default.yaml

Add --all to validate every discovered theme:

polytoken theme validate --all

The command exits non-zero on any hard error and reports per-file results.

Switching themes at runtime

Type /theme in the TUI prompt to open a typeahead of discovered valid themes.

• Up / Down move through the candidates.
• The TUI immediately redraws with the highlighted theme’s colors.
• Tab accepts the highlighted candidate and keeps the typeahead open.
• Enter applies the highlighted theme for the current session.
• Esc restores the previous theme and closes the typeahead.

Applied themes are session-local: Polytoken does not write the change to your config file. To make a theme permanent, set tui.theme-file in your config.

VFS theme resources

The built-in default theme is stored at polytoken://themes/default.yaml in the virtual filesystem. Inspect it, or copy it as a starting point:

polytoken vfs ls polytoken://themes
polytoken vfs cat polytoken://themes/default.yaml

For the full VFS documentation, see The Polytoken VFS.