How themes work

A theme decides how a site looks and what goes where. It does not add features, it does not own data, and it never installs anything on the operator's behalf.

One theme is active at a time. Switching does not touch content: every page, every module and every setting stays exactly where it was, and only the presentation changes.

Tokens

Colours, fonts, radius and spacing are declared as tokens rather than written into components. Each token a theme declares becomes a field in the admin panel, with a label and the right input, and the theme author writes no React for any of it.

That is also why a site can be recoloured by an operator without touching the theme's files. What the operator changes is stored per theme and per mode, so switching away and back finds their work intact.

Modes

Light, dark, or any mode a theme wants to name, each with its own token values, in the same manifest.

There is deliberately no such thing as a separate dark version of a theme. Two files drift: a colour changes in one and not the other, and nobody notices until a reader in the wrong mode meets grey text on a grey background.

Settings

Beyond tokens, a theme can declare its own settings: a tagline, a cover image, a Discord invite, a server address. Core renders the form, validates the input and stores the values, and the theme reads them.

Field types are text, url, color, richtext and image.

Component overrides

A theme can replace named components: the header, the footer, the hero. What it does not name keeps the platform's own version, so a theme that only wants a different footer is a manifest with one line in it.

Slots

A slot is a named place a module can put something into. Core declares a fixed set - the top of the layout, the start and end of the navigation bar, the top of the footer - and a theme can declare its own.

This is how a preset for a game community gets a live player count into its hero without the hero knowing what a player count is, and without the module that counts players knowing what a hero is.

Where a theme stops

If it holds data, it is a module. If it has an admin screen that manages something rather than configuring appearance, it is a module. A theme that installs software is not a theme, which is why suggestedModules shows a banner the operator can dismiss and does nothing else.