Theme Reference

This page describes the theme package format, one part after the other. Use it next to the tutorial in Make a Theme. Every name on this page comes from the validator (aivory-theme), the desktop renderer or the JSON Schema of the AIVory Code repository.

Folder Layout

Files and folders whose name starts with a dot are not part of a theme. The unpacker leaves them out.

The Manifest: theme.toml

The manifest accepts only the keys below. An unknown key is an error.

id = "harbor"
name = "Harbor"
description = "A calm dark theme with one decision at a time."
version = "0.1.0"
license = "MIT"
min_app = "2026.1.0"
catalog = 1
displays = ["desktop"]
tokens = ["tokens.toml"]

[author]
name = "Jane Doe"
url = "https://github.com/janedoe"

Tokens

A token file is TOML with the tables below. Layouts use token names, not raw values. The tables accept only the keys that are listed here. Unknown keys are an error.

colors

A color is #rrggbb or #rrggbbaa. All of these are required.

In a layout you write these names in props such as color, bg, border and tone: bg, surface, text, muted, accent, analysis, state.needsYou or only needsYou.

The app also checks 12 pairs for contrast (for example text on bg and surface, 4.5:1; muted, 3:1). A pair that fails keeps the value of Minimal, and the app notes it. The theme still loads.

fonts

serif is not bundled in the desktop app. It keeps the sans face and logs a note.

type

The five text sizes in px. Each is required and must be 6 to 72. Components pick one with the prop size. The app scales them with the interface text size.

space and radii

Both are open tables: you choose the names. A value is a number from 0 to 200.

The names radii.button, radii.card, radii.tile, radii.pane and radii.rail_item also set the corners of the screens that the app draws itself. The app caps them at 48.

motion and effects

motion has only easing and the table durations. A key such as fast_ms directly in [motion] is an error. Write [motion.durations] and fast = 120.

Strings

strings/<lang>.toml holds texts. A layout reads one as $strings.key. A nested table gives a dotted key: [nav] with home = "Home" is $strings.nav.home.

The desktop app reads strings/en.toml today. It does not pick a language by locale yet. A missing key shows the key itself.

Layout Files

A layout file is JSON with two keys:

{
  "$schema": "https://example.com/optional",
  "root": { "type": "panel", "title": "$strings.title", "children": [] }
}

$schema is optional and must be a string. Any other key at the top is an error. Do not put screen or display in the file: the path of the file sets both.

Nodes

A node is an object with type (a component of the catalog), or an object { "use": "<part>" }. A use node accepts only use and when.

A node may sit only in children, fallback, tiers.<tier>.template and classes.<class>. A node inside another prop is an error.

Values

when

{ "path": "$asks", "is": "empty" }

A when has one test. It accepts only path, is and value.

Parts

A part is a file parts/<name>.json with the same shape as a layout file. A layout inserts it with { "use": "<name>" }. Use parts for a top bar or a card that many screens share. The validator walks parts like layouts, in the class desktop.

Component Catalog

The catalog has 45 components. The catalog version is 1. In a watch layout only these components are allowed: stack, list, row, text, readout, badge, gauge, decision and composer.

Props that most components accept

spacer reads size only. card and panel read width, height, grow, pad and radius. Text clips with an ellipsis. A component does this, and a theme cannot turn it off.

Layout

Frame

Content

Session components

A settings layout without a settings_section is not used. Settings > Display must stay reachable, so the app then shows its own Settings screen.

Charts

Effects and scenes

The desktop app draws the fallback node of every effect and scene. The scenes and effects themselves are not yet supported. Build a theme that looks right with the fallback.

Window width

responsive holds a node for each width class under classes:

A class without a node uses the next smaller class. On the phone class only compact is allowed. On fold: compact and regular.

Session tiers

sessions draws one template for each count of live sessions. A live session is not parked and not done.

{ "type": "sessions", "gap": "gap", "tiers": {
  "1":     { "layout": "grid", "template": { "type": "card", "title": "$item.title" } },
  "13-30": { "layout": "list", "template": { "type": "row",  "title": "$item.title" } }
} }

Data Paths

A text that starts with $ is a data path. Segments use [A-Za-z0-9_]. A number segment is a list index: $sessions.0.title. A path that leads nowhere gives an empty text. Layouts have no formulas. The app computes all counts, orders and formats.

Values of a session:

A session has no transcript tail in the snapshot. Use transcript or terminal to show the lines. When a session is selected and $intent.mode is not alert, $intent.mode reads one.

Actions

A control calls one action of the app, and nothing else:

{ "type": "button", "label": "Open session",
  "on": { "press": { "action": "focus", "id": "$item.id" } } }

on accepts only press and key. There are no timers and no load events. A key event needs a combo such as "Ctrl+K" (modifiers Ctrl or Cmd, Alt, Shift, plus one key). The combos Ctrl+Shift+L, Esc and Escape belong to the app.

An argument name uses [a-z][A-Za-z0-9]*. An argument is a data path or a literal.

Assets and Limits

The image component does not draw files yet, so no layout can show a file of assets/images/ today. Images in previews/ are for the Settings screen and for the registry.

Validator

Run the validator in one of three ways:

A good theme prints ok: <id> <version>. A bad theme prints one line for each error and the count. The exit code is 1.

An error has the form <file> <JSON pointer>: <rule>. A pointer such as /root/children/2/on/press/action leads to the key.

Common errors

A Complete Minimal Theme

aivoryd theme init harbor writes this theme. It passes aivoryd theme dev harbor --once and prints ok: harbor 0.1.0. It has the 8 required screens. Each screen is a panel with the daemon version. Replace the panels to build your theme in the tutorial.

theme.toml

id = "harbor"
name = "harbor"
description = "A starter theme."
version = "0.1.0"
license = "MIT"
min_app = "2026.1.0"
catalog = 1
displays = ["desktop"]
tokens = ["tokens.toml"]

[author]
name = "Your Name"

tokens.toml

[colors]
bg = "#ffffff"
surface = "#f4f5f7"
text = "#15161b"
muted = "#6b7280"
accent = "#2563eb"
analysis = "#7c3aed"

[colors.state]
needsYou = "#d97706"
working = "#2563eb"
idle = "#6b7280"
parked = "#9ca3af"
error = "#dc2626"
done = "#16a34a"

[fonts]
ui = "sans"
mono = "mono"

[type]
xs = 11
sm = 12
md = 14
lg = 18
xl = 24

[space]
sm = 8
md = 12

[radii]
card = 8

[motion]
easing = "easeOut"

[motion.durations]
fast = 120

strings/en.toml

title = "Fleet"

layouts/desktop/warroom.json

{
  "root": { "type": "panel", "id": "warroom", "title": "$strings.title", "children": [
    { "type": "text", "value": "$daemon.version" }
  ] }
}

The other seven files (session, inbox, tasks, repos, settings, focus, decision) have the same content with another id. The folder also holds LICENSE and README.md.

What Is Not Finished

These parts exist in the format or in the code, but they do not work yet. The desktop renderer is apps/desktop of the AIVory Code repository.

Next Steps