Themes

A theme is how a wizard’s pages look: the colours of light and dark pages, two fonts, the shape of corners, cards and headings, and effects such as spider webs, embers or snow. A theme is a document of its own. It lives in the space, several wizards can wear it, and a wizard file carries the themes its wizard names.

A theme holds values only: no CSS, no files, no addresses. Everything a theme shows is drawn by the runner’s own code. So a theme is checked completely by its schema, and it looks the same wherever the wizard runs.

The chain in the definition

themes in the definition names the looks the wizard offers, in order. Each entry is the id of one of the space’s themes, or a built-in:

{
  "version": 1,
  "title": "Spukhaus-Exposé",
  "themes": ["halloween", "halloween-calm", "brand"],
  "steps": [ … ]
}

Without themes the wizard wears its space’s brand. themes holds at most 8 ids, each once.

Which theme shows where

The wizard offers its chain. The place that shows it chooses from it.

An id outside the chain shows the first theme. A wizard can’t insist on its theme, but a place can only choose among the themes the wizard offers.

The theme

Its JSON Schema is https://engenty.ai/schema/theme/v1/theme.json.

{
  "id": "halloween",
  "name": "Halloween",
  "version": "1.0.0",
  "base": "brand",
  "colors": [
    { "scheme": "dark", "accent": "#ff7a1a", "background": "#140b1f", "text": "#f3eaff" },
    { "scheme": "light", "accent": "#d9480f", "background": "#fff4e6" }
  ],
  "fonts": { "heading": "Creepster", "text": "Nunito" },
  "shape": { "radius": "round", "cards": "glass", "headings": "normal" },
  "effects": [
    { "id": "glow" },
    { "id": "corners", "kind": "webs" },
    { "id": "figures", "costume": "bat", "motion": "fly" },
    { "id": "particles", "kind": "embers" }
  ]
}

Colours

colors holds one entry per scheme, light or dark, each once. Each entry has accent, background and text as #rrggbb, and leaves out what comes from the base. Every other colour of the page (buttons, fields, cards, borders) is worked out from these three.

Fonts

heading and text each name a font that engenty wizards ships, or brand for the space’s own.

The shipped fonts load from engenty wizards itself, never from another site: Inter, Figtree, DM Sans, Nunito, Fredoka, Bricolage Grotesque, Fraunces, Playfair Display, Lora, Young Serif, Caveat, Creepster and Nosifer. Creepster and Nosifer are display fonts for headings.

A space’s own font, for example the one its website uses, belongs to its brand, not to a theme: uploaded as a file, or loaded from the website’s address after you confirm the licence (see Space). A theme only names it, with brand. A theme that goes to another space shows that space’s brand font, or a shipped font of the same kind.

Effects

• One kind each. corners, particles and pattern take one kind. In the studio, choosing one switches the other off.
• Never in the way. Effects sit over or behind the page and never take a tap or a click.
• Reduced motion. For people who ask their device for less motion, nothing moves: flying figures, particles and peeking figures go, the spider and the fog stand still.
• New effects. The library grows with runner releases. A runner that doesn’t know an effect or an option leaves it out, so a theme stays valid on older installs.

Ids and scopes

engenty, wizard and wizards are reserved as ids, and @engenty and @wizard as scopes.

The catalog for themes isn’t open yet. Until then a theme reaches another space in a wizard file.

In a wizard file

wizard.json carries the themes its wizard names, in full, beside the definition:

{
  "format": "engenty-wizard",
  "version": 1,
  "definition": { "themes": ["halloween"], … },
  "themes": [{ "id": "halloween", "name": "Halloween", … }]
}

The import puts them into the space you import into:

• The same theme is there. Same id, same content: the space keeps its own, nothing doubles.
• Another theme has the id. The imported one comes in under a free id, halloween-2, and the wizard’s themes names that one.
• New. It comes in as it is.

A space keeps at most 40 themes. A wizard sent from your computer to the cloud takes its themes along, and they replace the cloud space’s themes with the same ids.

From the studio and from agents

The studio’s “Look” section edits the theme a wizard wears (see Build a wizard). The first change makes a theme named after the wizard.

Agents and MCP clients use two operations of edit_wizard:

A theme saved from the studio or an agent has no scope.

Why no CSS

Free CSS and files would run in the run page itself, next to what people type. CSS can send answers to another site, or hide and relabel what must stay as it is: the question before a connector acts, a sign-in, the AI labels. A theme’s address for a font or a picture would send every visitor’s IP address to that site. Values only avoid all of it, and a schema can check them. The reasoning is in docs/plans/themes.md.

Styling around the runner

A page that shows the runner as a component (OpenUI) can style around it with these names. They stay the same across releases. Anything else on the runner’s elements may change.

The variables are for reading. The theme sets them.

.wizard-title { letter-spacing: 0.04em; }
.wizard-button {
  border-radius: 0.5rem;
  outline: 2px solid var(--wizard-accent);
}