Custom Themes

The Cockpit's ◐ Theme menu lists the eight default themes (Themes) and any theme you add as a file. A theme is a name, a mode and 12 colours; canon works out every other colour the Cockpit and its boards need from those 12.

Where the files go

~/.canon/themes/ (or $CANON_HOME/themes/ if you set CANON_HOME). Each .json file directly in that folder is one theme. Click Create a sample theme at the bottom of the ◐ Theme menu: canon creates the folder with a working example.json and a short README.md, then opens it. Once the folder exists, the menu shows Show themes folder instead. It never overwrites a file that is already there, and it adds nothing to a folder that already exists.

A new or changed file shows up the next time you open the menu. Your theme appears with the built-ins of its mode (Light or Dark); pick it like any other.

The format

{ "name": "Example Dark", "mode": "dark", "colors": { "bg": "#1f2430", "surface": "#272d3a", "border": "#3a4252", "text": "#eef1f6", "body": "#c4cad6", "muted": "#a3abba", "accent": "#5aa9e6", "ok": "#6cc070", "warn": "#e6b450", "bad": "#ef6b73", "info": "#79b8ff", "term": "#171b24" } }
Key Colours
bg the page background
surface panels, cards and menus
border lines and outlines
text headings and main text
body body text
muted secondary text and the Open column
accent buttons, links, selection and focus
ok done and success
warn needs attention, working
bad failures, needs you
info in progress
term the terminal background (required; used once the terminal follows the theme)

The rules

A theme file is read only when all of these hold:

If a key appears twice, the last one counts.

The same rules are written as a JSON Schema in tools/sprint-check-app/theme.schema.json; the file-level rules (name, link, size, encoding, nesting) are in its description.

When a file is refused

A file that breaks a rule is never applied. It is listed under Your own in the ◐ Theme menu with the reason, for example my-theme.json: colors.accent must be #rgb or #rrggbb. Fix the file and reopen the menu.

If the theme you picked is later deleted or refused, the Cockpit shows Canon Dark or Canon Light for that mode and keeps your pick, so fixing the file brings your theme back.

Readability

The default themes are all held to WCAG AA. Your theme is checked against the same floor: 4.5:1 for text on the background and for muted text on panels, 3:1 for the accent on the background and for text on the accent. A theme below it can still be used; its card says Low contrast, and hovering the mark shows which pair failed and its ratio.

Safety

Anything can write to that folder, so canon treats its files as untrusted. Both board servers check every file with the rules above and the page checks each one again before using it. Colours are set one variable at a time, never as CSS text, and names and reasons are shown as plain text. Create a sample theme and Show themes folder open that one folder in your file manager, and nothing else.