VTX 1 · extension · draft d01
VTX Themes 1: branded themes
§1Status and scope
Themes 1 lets a server brand what the client draws: colours for light and dark mode, the terminal palette, typefaces, base text size, corner radius, density, icons and a logo. A theme is a cached, content-addressed resource that applies to the whole scene or to one region, so one console can host several branded applications side by side. This is draft d01 of an extension of VTX 1, in conformance profile 2, built on the core at draft d03.
- What a theme never touches. The trusted zone, the user's accessibility settings, and what content says or whether it is visible: a theme restyles, it cannot hide.
- Custom components are a separate extension, Composites 1.
§2Capability, resource kind, and where a theme applies
A client that accepts theme: true takes theme resources and the theme prop.
- Resource kind
theme/vtx. One theme document (Section 3) in deterministic CBOR (RFC 8949, Section 4.2.1), so the same theme always has the same hash. The client fetches it once and keeps it across sessions, in the cache partitioned per server (v1 Section 10). - The
themeprop. Onroot, set withpatch, and onregionnodes; its value is the theme's resource hash. It applies to the node and everything inside it, and the nearest themed ancestor wins. The root's theme also brands the client's window: title bar, logo and background. - Partial themes. A field a theme leaves out comes from the next themed ancestor, then from the client's defaults. A region theme can change only the accent colour.
- Switching. Until a theme has arrived, the client keeps the styling it had. It then restyles the whole subtree in one frame.
- Without the capability. The server sends no theme; a client that meets a
themeprop anyway ignores it, as it ignores any unknown prop.
§3Theme content
Every field is optional, so a theme states only what it changes.
| Field | Type | Meaning |
|---|---|---|
name |
text | Display name; informative only |
colors.light, colors.dark |
palette (below) | Colours per mode; at least one when colors is present |
fonts.ui, fonts.mono, fonts.heading |
family name or font resource | Interface text; grids and code; headings |
text.base |
10–24 | Base text size in px at scale 1 |
radius |
0–24 | Corner radius of components, px |
density |
compact, normal, comfortable |
Spacing inside and between components |
icons |
map of icon name to glyph resource | Replaces core icons by name, up to 1,024 |
logo |
{ res, alt } |
An image or glyph resource for the client's title area, with its text alternative |
Palette. All colours are #rrggbb.
| Key | Used for |
|---|---|
fg, bg, muted, accent, info, success, warning, critical |
The v1 colour roles, wherever they appear: components, grids, vector surfaces |
panel |
Raised areas: cards, groups, overlays |
border |
Dividers and outlines |
on_accent |
Text and icons on accent-coloured controls |
focus |
Focus rings |
ansi |
16 colours for p0–p15, the terminal palette; p16–p255 stay fixed |
The client uses the variant that matches DISPLAY's dark. When the theme lacks that variant, the client uses its own palette for that mode rather than inverting the other one.
{"name":"Helper agent","colors":{"light":{"accent":"#6D28D9","on_accent":"#FFFFFF","focus":"#6D28D9"},"dark":{"accent":"#C4B5FD","on_accent":"#1E1033","focus":"#C4B5FD"}},"radius":16}
§4Precedence and accessibility
The user's accessibility settings come first, then the theme, then the client's defaults.
- User settings win. The user's text size scales
text.base.reduced_motionholds whatever the theme says. In high-contrast or forced-colour mode, the client may set the theme's colours aside entirely. - Contrast floor.
fg,mutedand the four status roles need at least 4.5:1 againstbg,on_accent4.5:1 againstaccent, andfocus3:1 againstbg(WCAG 2.2, criteria 1.4.3 and 1.4.11). The client replaces any colour below its floor with its own default for that role. A server SHOULD check before sending; the definitions include the check. - Fonts. A client may refuse a font that fails sanitising or lacks glyphs it needs, and falls back to its default for that slot.
- Never themed. The trusted zone keeps the client's own look. CLAIM's colour stays separate and labelled as claimed (v1 Section 12). The logo appears only in the application's title area, never in or beside the zone.
§5Terminals and surfaces under a theme
A theme reaches every place a colour role or the terminal palette is used.
- Grids. Role colours and
p0–p15come from the nearest theme;fonts.monoapplies unless the grid setsfont. A theme change recolours existing cells that use roles orp0–p15; cells in#rrggbborp16–p255keep their colour. - The VT engine answers OSC 4, 10 and 11 colour queries from the theme in effect for the grid when there is one, and from DISPLAY otherwise. DISPLAY keeps reporting the client's own, unthemed colours.
- Vector surfaces (Surfaces 1) paint with roles, so they follow the theme. Image surfaces are left as they are.
§6Text form and application interface
Applications declare themes by name and never handle hashes; the server does the encoding.
- Declaring. An application writes
{"kind": "theme", "name": …, "theme": {…}}. Names are lower case, up to 32 characters, and belong to the application's session. The server encodes the theme, hashes it, offers it to the client, and replaces the name with the hash in every later op. - Redeclaring a name points later ops at the new theme. Nodes already themed keep their theme until the application patches them.
- On the wire,
themeis always a resource hash. - Deterministic encoding. Map keys are sorted by their encoded bytes and integers take their shortest form (RFC 8949, Section 4.2.1); themes contain no floats. Two test vectors, Fjord and Helper, are in
ext/theme-1/examples/vectors.json.
{"kind":"theme","name":"helper","theme":{"name":"Helper agent","colors":{"light":{"accent":"#6D28D9","on_accent":"#FFFFFF","focus":"#6D28D9"}},"radius":16}}
{"op":"patch","id":"root","set":{"theme":"fjord","title":"Fjord operations"}}
{"op":"open","id":"agent","type":"region","title":"Support agent","theme":"helper"}
§7Security and privacy
A theme is styling data: it cannot fetch, run code or reach the trusted zone.
| Threat | Mitigation |
|---|---|
| Network access | Fonts, icons and the logo arrive only as resources the server offers |
| Hostile font files | Fonts are sanitised as in v1 Section 10 |
| Hiding content with colour or size | The contrast floor (Section 4) and the bounded text.base; a theme has no per-node visibility or size |
| Tracking across servers | Themes are cached per server identity, like every resource |
| Impersonating another service with a logo | The trusted zone always shows the verified server identity, and the logo never appears beside it |
§8Wire changes and definitions
Themes need no new frames, ops or error codes.
| Where | Change |
|---|---|
| Capabilities | theme |
| Resource kinds | theme/vtx |
| Scene props | theme on root and region |
| Application interface | The theme control line |
The bundle's ext/theme-1/ holds:
| File | Defines |
|---|---|
vtx-theme-1.cddl |
theme-doc and the new resource kind; load after vtx-wire-1.cddl |
vtx-theme-1.schema.json |
One theme, for authors and tools |
vtx-ops-theme-1.schema.json |
Every v1 op, with theme on regions |
vtx-app-theme-1.schema.json |
The application interface with theme lines |
examples/ |
The Fjord and Helper themes, an application stream and a wire stream, 14 lines that must be rejected (12 by the schemas, 2 for naming an undeclared theme), and a theme that passes the schema but fails the contrast floor |
examples/vectors.json |
Each theme's deterministic CBOR and hash |
tools/validate.py runs 44 checks for this extension, including the contrast floor and the deterministic encoding, and every check in the bundle passes.