Custom themes

A custom theme is a small file that starts from another theme and changes only the colors you choose. You can ask an agent to make one, or change one yourself in Settings. hob checks every theme with the same rules, so a theme that makes text hard to read is never applied.

Ask an agent for a theme

Describe the look you want. Name a theme to start from if you have one in mind.

The agent reads the list of colors a theme can set and writes the theme file into the themes folder in the hob data directory. Then it checks the file with hob's validator. When a value is not accepted, or text falls below the contrast that hob requires on a surface, the agent sees the problem at that color and fixes it before you see anything.

When the file is valid, the agent previews it. Your window changes to the new theme, and a bar shows Keep and Revert with a countdown.

Keep it or revert it

• Keep selects the theme. It stays selected after a restart.
• Revert puts back the theme you had.
• When the countdown ends without a choice, the preview reverts.

Some themes are made for one color scheme, such as a dark space theme. When the window shows the other scheme, the preview switches it and the bar says so. Show light and Show dark let you see both halves before you choose. Keep also saves the scheme you see; Revert puts back your Color scheme, including System.

Only you choose. The agent waits and learns whether you kept the theme, reverted it, or let the countdown end, so it can try another version when you ask. A preview shows only in the window that holds the agent's pane, and nothing is saved to your settings until you choose Keep.

To refine the theme, tell the agent what to change. It edits the same file and previews it again.

Change a theme yourself

Open Settings → Appearance → Custom themes. Choose a theme, then Duplicate to make a copy that you can change. The copy keeps every color of the theme it starts from until you change one.

The editor groups the colors as Surfaces, Text, Borders, Accent, Status, and others. Each color you have not set shows the value it inherits and where that value comes from. Change a color with the swatch or type a value; Reset puts back the inherited value. The editor checks each change at once and shows any problem next to that color.

Your changes show in this window while you edit. Save writes the file. Cancel, closing the editor, or leaving Settings puts back the theme you had. After you save, choose the theme under Theme to use it.

If the file changes on disk while you edit it, for example because an agent edited it, the editor keeps your changes and asks whether to discard them or save yours over the file.

What a theme file contains

Each custom theme is one JSON file in the themes folder. The file name is the theme's id: lowercase letters, digits, and dashes.

{
  "name": "Dusk",
  "extends": "ink",
  "colors": {
    "dark": {"accent": "#e8a243", "surface-app": "#14161c"},
    "light": {"accent": "#b86e24"}
  }
}

extends names the theme to start from; without it, a theme starts from hob style. A color the file does not set keeps the value of that theme. Every theme defines both dark and light colors. prefers says which scheme a theme is made for: "dark", "light", or "both" (the default). When you choose a theme that prefers the other scheme, hob switches the Color scheme to it and shows a short message with a button that switches it back. With Color scheme System, hob compares with what System shows now. terminal names the terminal palette that Terminal theme → Auto uses with this theme. Without it, Auto uses the palette of the built-in theme it starts from.

The Theme picker lists your custom themes after the built-in ones. A theme that breaks a rule stays in the list with its problem and cannot be chosen. If the selected theme stops being valid, hob uses the theme it starts from; if its file is removed, hob uses hob style. A message tells you why. Your choice is kept, so the theme returns when the file is fixed.

Custom themes apply in the desktop app and the browser IDE. hob roam keeps hob style.

Bring a theme to a remote Host

When a window shows a paired remote Host, Settings → Appearance → Custom themes offers Import from this computer. It lists the custom themes and terminal palettes of the computer you sit at that the remote Host does not have yet. A theme that already looks the same there is not listed, even under another name, so the list holds only what is new. An imported theme keeps its look without the themes it started from, and brings its paired terminal palette along. If the remote Host already has a different theme in a file of the same name, the import is saved under a new file name, keeps its theme name, and tells you.

An import never changes the theme on its own: the remote Host may also have its own desktop. Choose Use it after the import, or pick the theme later under Theme.

Terminal palettes

Terminal output has its own palette: the background, the text, the cursor, the selection, and the 16 ANSI colors that programs use. Each built-in theme has a built-in palette with the same name. You can make your own palette the same way you make a theme.

The agent writes the palette file into the terminal-themes folder in the hob data directory, checks it, and previews it. Open terminals and command blocks in your window change at once, and the same Keep and Revert bar appears. Keep selects the palette under Settings → Terminal → Terminal theme.

To change a palette yourself, open Settings → Terminal → Custom terminal palettes and duplicate one. The editor works like the theme editor; its colors are grouped as Basics, Normal colors, and Bright colors.

hob checks that the text, the cursor, and selected text stay readable on the background. It does not check the ANSI colors, because programs choose them. Palette values are plain colors, such as #1e1f1c or rgb(30, 31, 28); the selection color can be translucent.

A theme and a terminal palette are separate, so they can have the same name. To pair them, set the theme's terminal to the palette's id, or choose the theme's terminal palette in the theme editor. If a palette cannot be used, hob uses the palette it starts from, or the theme's own palette when the file is gone, and tells you why. The theme still applies.

hob theme tokens                  # colors a theme can set, fallbacks, accepted values
hob theme list                    # themes and the absolute themes folder path
hob theme show ink --resolved --mode dark   # every color and where it comes from
hob theme validate dusk           # check <themes folder>/dusk.json, or pass a file path
hob theme preview dusk            # Keep / Revert in the person's window; prints the outcome
hob theme tokens --terminal       # terminal palette keys, value forms, and contrast floors
hob theme preview --terminal dusk # preview a terminal palette; Keep selects it

Next