Looks
and Themes

A plugin's script is built without the app's API: imports of it are left as names and answered by the page at load time (decision "Plugins import only the app's versioned API"). So when the app exports components from its web module, every plugin gets the very same functions, from the base bundle the page loaded once:

// src/api/v3/web.ts (the app)
export { Sheet, Button, List, Toolbar } from "../../web/components.tsx";
export { Panels } from "./panels.web.ts";

// plugins/notes/web.tsx
import { defineFacet } from "@acme/app/v3";
import { Panels, Sheet, Button } from "@acme/app/v3/web";

export default defineFacet((host, self) => {
	self.contribute(Panels, { title: "Notes", Component: () => <Sheet><Button>New note</Button></Sheet> });
});

Two things follow. A plugin never ships a copy of the app's components, so a page with twenty plugins loads them once. And when the app improves a component, every plugin shows the improvement after the app's next restart, without being rebuilt. Components that change shape incompatibly get a new API version, as any API does.

The app's stylesheet, part of the base bundle, defines the look as CSS custom properties on the page's root:

:root {
	--accent: #e8590c;
	--bg: #111317;
	--fg: #e8e8e8;
	--muted: #8a8f98;
	--radius: 10px;
	--font: "Inter", system-ui, sans-serif;
}

The app's components use only these variables, never fixed colours. A plugin does the same in its own CSS:

/* plugins/notes/notes.module.css */
.card { background: color-mix(in srgb, var(--bg) 92%, var(--fg)); border-radius: var(--radius); }
.title { color: var(--accent); font-family: var(--font); }

import styles from "./notes.module.css";
<div className={styles.card}><h2 className={styles.title}>Shopping</h2></div>

Because everything reads the variables, changing the variables changes everything: the app's components and every plugin's parts, at once, without reloading anything. That is what makes themes cheap.

Keeping plugins apart

Two plugins both writing .card { ... } would overwrite each other's styles. CSS modules solve that: esbuild gives each class in a *.module.css file a name unique to that file, and the import returns the mapping. The build already collects each web facet's CSS into one stylesheet, served next to its script and swapped when the plugin reloads, so nothing new is needed except the convention. Plain CSS files still work; their class names should then start with the plugin's name.

A terminal has no stylesheets, but the same split works. The app's terminal module exports its components, built on whichever terminal UI library the app chose, and a theme lookup by role:

// plugins/notes/tui.ts
import { defineFacet } from "@acme/app/v3";
import { Panels, Box, theme } from "@acme/app/v3/tui";

const render = (notes) => Box({ title: theme.fg("accent", "Notes"), lines: notes.map((n) => theme.fg("fg", n.text)) });

A plugin never writes raw escape codes; it asks for a role (accent, muted, error), and the app's lookup turns the active theme's colour into what the terminal supports: true colour, or the nearest of 256 colours.

A theme names a colour for each role. Roles, not surfaces: an accent is an accent on a page and in a terminal. So the registry lives in the app's shared API module, and its entries are plain data, safe to import from any host kind:

// src/api/v3/index.ts (the app)
export type Theme = {
	id: string;
	name: string;
	mode: "dark" | "light";
	colors: { accent: string; bg: string; fg: string; muted: string; error: string; warning: string; success: string };
	web?: Readonly<Record<string, string>>;   // extra CSS variables: radius, fonts, shadows
	tui?: Readonly<Record<string, string>>;   // terminal-only overrides: a 256-colour fallback for a role
};
export const Themes = defineRegistry<Theme, readonly Theme[]>("acme.themes", { version: 1 });

The app contributes its default themes from its own plugins, like any other contribution. Its theme picker lists the registry's current entries; the choice is a user preference.

On the web, the page watches Themes and the user's choice; when either changes it writes the active theme's colours (and its web extras) as CSS variables on :root. Nothing reloads; the browser repaints.

In the terminal, the app's theme lookup reads the same entry; the next redraw uses the new colours.

A theme plugin is the smallest kind of plugin there is: data, contributed. As single-file plugins (decision "Single-file plugins"), one per surface it wants to be visible on, sharing the data:

// plugins/solarized.web.ts
import { defineFacet, Themes } from "@acme/app/v3";
import { solarized } from "./solarized-data.ts";   // or inline: single-file plugins import only the API
export default defineFacet((_host, self) => self.contribute(Themes, solarized));

Since a single-file plugin may import only the app's API, a theme with two surfaces is either two files with the data inlined, or a small directory plugin (plugins/solarized/ with theme.ts, web.ts, tui.ts).

When its author changes a colour, the watcher marks the plugin dirty; the next rollout reloads it on the server and in every open page and terminal; the registry recomposes; pages that use Solarized repaint. No page reloads, nothing on screen is lost.

When the app changes its roles

The app adds a role (link) in a later release. Old themes do not name it. The registry's version guards this: the app bumps Themes to version 2 and maps version 1 entries by filling the new role from the default theme. An old theme keeps working, slightly less complete; nobody's page breaks.

A plugin cannot change the app's base stylesheet or its components: those are base code, changed by the app's release. It can contribute a theme (the app's looks, re-valued), style its own parts with scoped CSS that reads the tokens, and place UI through registries like Panels. That line keeps a page coherent with twenty plugins from twenty authors, and keeps one bad plugin from breaking everyone's layout.