svelte-kit-vice/docs/theming/guide.md

---
title: Eidos Theming — Authoring guides
type: guide
audience: human + agent
status: current
source: migrated from src/uix/eidos/THEMING_GUIDE.md (2026-07-02, docs-book F7.3; originally extracted from THEMING §8 + §9)
---

# Eidos Theming — Authoring guides

> The two theming how-tos: add a new component and define a theme. Extracted
> from [`THEMING.md`](./reference.md) (the E1 reference) to
> live as an E4 guide. The token contract holding all of this together is
> [`canon/tsc.md`](../canon/tsc.md); the transversal systems every recipe
> must consume are [`canon/recipe-contract.md`](../canon/recipe-contract.md).

---

## How to add a new component

Assuming you already have the morfo, the soma and the eidos wrapper
scaffolding (`src/uix/eidos/components/{name}/`):

### Step 1 — Decide which tokens you need

Look at similar components (`button`, `toggle`, `switch`). Identify which
dimensions your component exposes:

- Does it have `data-color`? → palette tokens.
- Does it have `data-variant`? → variant tokens.
- Does it have `data-size`? → size tokens.
- How many parts does it have? → per-part tokens.

### Step 2 — Add the recipe in `lib/recipes/base.ts`

```ts
// Within THEME_BASE_RECIPE_TOKENS:
'my-component': {
  // size tokens — scope 'root' (stable)
  'height-md': '36px',
  'padding-inline-md': 'var(--space-3)',
  'gap': 'var(--space-2)',
  'radius': 'var(--radius-md)',

  // per-color literal definitions — scope 'root'
  'primary-solid': 'var(--color-primary-solid)',
  'affirm-solid':  'var(--color-affirm-solid)',
  'threat-solid':  'var(--color-threat-solid)',

  // dynamic palette — 'host' default + per-color overrides
  'palette-solid': {
    declarations: [
      { value: 'var(--my-component-primary-solid)', scope: 'host' },
      { value: 'var(--my-component-affirm-solid)',  scope: 'color:affirm' },
      { value: 'var(--my-component-threat-solid)',  scope: 'color:threat' }
    ]
  },

  // derived tokens — scope 'host' (deps inferred)
  'solid-bg': {
    value: 'var(--my-component-palette-solid)',
    scope: 'host'
  }
}
```

### Step 3 — Regenerate

```bash
npm run generate:eidos-css
```

If your config violates the TSC, the regeneration tells you:

```
Eidos recipe scope contract violations:
  - my-component.solid-bg (scope root): dependency 'palette-solid' is only
    declared at scopes [host], none of which is reachable from the
    consumer's scope.
```

### Step 4 — Write the recipe CSS

`src/uix/eidos/components/my-component/my-component.css`:

```css
[data-my-component] {
  /* Private tokens — only this recipe reads them */
  --_my-component-bg: var(--my-component-solid-bg);
  --_my-component-radius: var(--my-component-radius);

  display: inline-flex;
  align-items: center;
  padding-inline: var(--my-component-padding-inline-md);
  height: var(--my-component-height-md);
  border-radius: var(--_my-component-radius);
  background: var(--_my-component-bg);
  gap: var(--my-component-gap);
}

[data-my-component][data-disabled] {
  opacity: var(--opacity-disabled);
  pointer-events: none;
}
```

### Step 5 — Wire the CSS

Code-split components import their own CSS from the wrapper `.svelte`;
layout primitives and shared visuals aggregate in `index.css`:

```css
@import './components/my-component/my-component.css';
```

### Step 6 — Verify

```bash
npm run generate:eidos-css
npm test -- src/uix/eidos
npm run morfo:check
node --import tsx/esm scripts/eidos-lint.ts my-component
```

### Common anti-pattern: declaring composed tokens at `:root`

```ts
// ❌ WRONG — the TSC will fail
'my-component': {
  'palette-solid': { value: 'var(--color-neutral-solid)', scope: 'host' },
  'solid-bg': 'var(--my-component-palette-solid)'  // ← implicit 'root' scope, deps live in 'host'
}

// ✓ CORRECT
'my-component': {
  'palette-solid': { value: 'var(--color-neutral-solid)', scope: 'host' },
  'solid-bg': {
    value: 'var(--my-component-palette-solid)',
    scope: 'host'
  }
}
```

---

## How to define a theme

Every theme declares **what it is** — `appearance: 'light' | 'dark'`. It is
mandatory, never inferred: it governs `color-scheme`, the first declaration
of the theme block, which rules the surface the UA paints and eidos cannot
style (the native `<select>` option popup, form controls, scrollbars).

Three words, three meanings, no overlap:

| Word         | Means                       | Lives in                     |
| ------------ | --------------------------- | ---------------------------- |
| `mode`       | the PREFERENCE the user set | `data-mode`                  |
| `theme`      | what is PAINTED             | `data-theme`                 |
| `appearance` | what the theme IS           | `ThemeDefinition.appearance` |

A `-light` / `-dark` suffix on a theme id is the default resolver's **lookup**
convention (`${theme}-${mode}`), not a source of truth; the config validator
refuses a theme whose suffix contradicts its declared `appearance`. (The name
`colorScheme` is taken in eidos by the seed-derived palette,
`applyColorScheme` — hence `appearance`.)

Eidos supports **3 modes** of theme definition:

### Mode 1 — A patch over the base theme (recommended)

Change only what you need; everything else follows the base:

```ts
import { ActiveEidos } from '$uix/eidos';

ActiveEidos.create({
  themeBase: {
    semantics: {
      color: {
        roles: {
          primary: 'blue',     // primary uses the Radix blue scale
          secondary: 'plum'
        }
      }
    },
    primitives: {
      typography: {
        families: {
          primary: { family: 'Inter' }
        }
      }
    }
  },
  applyDom: true
});
```

### Mode 2 — A full config

For authoring from scratch:

```ts
import { ActiveEidos, defineEidosConfig } from '$uix/eidos';

const config = defineEidosConfig({
  primitives: { /* … */ },
  semantics: { color: { /* … */ } },
  themes: {
    'acme-light': { appearance: 'light', color: { /* … */ } },
    'acme-dark': { appearance: 'dark', color: { /* … */ } }
  }
});

ActiveEidos.create({ config, applyDom: true });
```

### Mode 3 — A CSS-only theme (no TypeScript)

Eidos publishes the contract as empty CSS for externals to fill:

```ts
const contract = activeEidos.renderContractCss({
  themeSelector: "[data-theme='acme-light']"
});
// Output:
// [data-theme='acme-light'] {
//   --scale-blue-9: ;
//   --color-primary-solid: ;
//   --size-md-control-height: ;
//   ...
// }
```

The consumer fills in the values:

```css
[data-theme='acme-light'] {
  --scale-blue-9: #006adc;
  --color-primary-solid: var(--scale-blue-9);
  --size-md-control-height: 38px;
}
```

And loads that CSS alongside Eidos's. With `themeSource: 'css'`,
`ActiveEidos` generates no theme of its own.

### Versioned persistence

```ts
const document = activeEidos.toDocument();
// → { kind: 'uix.eidos-config', version: 2, options: {...} }

const json = activeEidos.serialize();
localStorage.setItem('user-theme', json);

// Later
const hydrated = createActiveEidos({
  config: JSON.parse(localStorage.getItem('user-theme')!),
  prefs, dom
});
```

The document envelope carries a `version` for future migrations. A v1
document (written before `ThemeDefinition.appearance` became mandatory) is
rejected, not migrated — nobody can guess whether an old theme was light or
dark.

---

## How to kill the dark-mode flash

`data-theme` / `data-mode` and the rest of the preference attributes are
written by `ActiveEidos.apply()` and by the prefs DOM projection — that is,
after hydration. On a static build (no server, no hooks, `src/app.html` with
no script) that is several frames after first paint, and a dark-mode user
watches a light page turn dark.

The fix is a tiny script in `<head>` that stamps the SAME attributes before
paint. It must not be hand-written: a second, hand-rolled copy of the
resolution cascade drifts from the real one on the first rename. UIX compiles
it instead, from the runtime's own modules.

### Step 1 — Generate the artifact (once, and after touching the schema)

```bash
npm run generate:boot
```

Writes `src/uix/active-uix/generated/boot.js`, checked in. It is not a bundle
you have to place: it is two constants — `UIX_BOOT_SCRIPT`, the exact text that
goes inside the `<script>` tag, and `UIX_BOOT_CSP_HASH`, the `script-src` hash
of that text. A vitest keeps both in sync with a live compile, so a stale
artifact fails the gate rather than shipping.

The body never carries your parameters — they ride a `data-uix-boot` attribute
of the same tag — so the hash is constant per framework version. That is what
makes step 4 possible.

### Step 2 — A placeholder in `src/app.html`

```html
<head>
	%sveltekit.head%
	%uix.boot%
</head>
```

**Below `%sveltekit.head%`**, and the order is load-bearing. On a prerendered
site Kit publishes the policy as a `<meta http-equiv="content-security-policy">`
inside `%sveltekit.head%`, and a `<meta>` policy governs only what comes after
it. A boot placed above it is outside the policy — which is evading the CSP,
not satisfying it — and the trick buys nothing the moment the same policy
arrives as a header.

### Step 3 — Three lines in `src/hooks.server.ts`

```ts
import { renderUixBootScript } from '$active-uix/boot/render';

export const handle = ({ event, resolve }) =>
	resolve(event, {
		transformPageChunk: ({ html }) =>
			html.replace('%uix.boot%', () =>
				renderUixBootScript({
					defaultLocale: 'es',
					themeIds: eidos.listThemes()
				})
			)
	});
```

`renderUixBootScript` returns a string and nothing else — the framework does
not own `app.html` and does not install a hook.

**The replacement is a FUNCTION, always.** Given a string,
`String.prototype.replace` expands `$&`, `` $` `` and `$'` inside it, and those
two characters can appear in a theme id or a storage key: `$'` splices in
everything that followed the placeholder and the `<script>` ends early. A
function replacement is inserted verbatim, which is the only form that keeps
the guarantee the tag's own tests make.

One hook covers a fully static build as well: `adapter-static` renders its
prerendered pages and its `200.html` fallback through `server.respond`, so the
transform runs for both.

### Step 4 — Name the hash in `svelte.config.js`

```js
import { UIX_BOOT_CSP_HASH } from './src/uix/active-uix/generated/boot.js';

const config = {
	kit: {
		csp: {
			mode: 'hash',
			directives: { 'script-src': ['self', UIX_BOOT_CSP_HASH] }
		}
	}
};
```

This is the canonical recipe. Kit computes hashes for the scripts IT emits and
fixes the policy before `transformPageChunk` runs, so the boot's own hash is
yours to declare — and it never changes until you upgrade UIX.

**The constant carries no quotes, because Kit adds them.** It recognises a
`sha256-…` source and writes `'sha256-…'` into the policy itself. A site that
sends its own `Content-Security-Policy` header instead of using `kit.csp` has
to quote it: `script-src 'self' 'sha256-…'`. Unquoted, the token is not a valid
source expression at all — the browser ignores it and blocks the script, in
every engine.

> **Adding a hash to a `script-src` that already carries `'unsafe-inline'`
> makes the browser IGNORE `'unsafe-inline'` and block every other inline
> script on the site, including Kit's own start-up.** That is how CSP Level 2
> and later are specified, not a UIX rule, and it is the one thing here that
> can take a page down while it fixes a flash. If your policy relies on
> `'unsafe-inline'` today, move every inline script to a hash (or a nonce) in
> the same change, or do not add this one.

Skip this step entirely when the site has no CSP.

### The nonce — an emergency exit, not the recipe

`renderUixBootScript({ …, nonce })` exists for a site that runs its OWN policy
and issues its own nonces. That site writes the header by hand, so if it stays
with the hash it also writes the quotes by hand — `'sha256-…'`, step 4. Two
things to know before reaching for the nonce:

- **`event.locals.nonce` does not exist.** Kit starts `locals` as `{}` and
  never writes a nonce into it. Passing it renders no attribute at all, the
  browser blocks the script, and the flash comes back — silently. The only
  nonce Kit exposes is the `%sveltekit.nonce%` substitution, which happens
  across the whole template BEFORE `transformPageChunk`; a site that wants it
  carries it through a placeholder of its own (`%uix.boot:%sveltekit.nonce%%`
  in `app.html`, a regex replacement in the hook).
- **A prerendered page has no nonce at all.** Kit rejects `%sveltekit.nonce%`
  in the template and `mode: 'nonce'` when prerendering, because the value
  would be baked into a file served to everyone. On `adapter-static` the hash
  is the only option.

The nonce must fit the CSP Level 3 nonce grammar (base64 or base64url
characters, at most two trailing `=`), and Kit's always does: it is base64.
Outside that grammar the value is not a valid `'nonce-…'` source — engines that
implement the grammar never match it, and the tolerance some engines show for a
stray `=` is nothing a portable policy can rely on — so `renderUixBootScript`
throws `ActiveUixInvalidBootNonceError` instead of writing it into the tag.

### The three parameters, and why they are yours

- `defaultLocale` — the locale you passed to `createActiveUix({ langs })`. The
  preference schema is built around it, so a boot given a different one
  resolves a different `lang` than the runtime will.
- `themeIds` — `eidos.listThemes()`. It feeds the "is this family already a
  complete theme id?" branch; without it every family gets a `-light` /
  `-dark` suffix appended and `data-theme` disagrees with the runtime.
- `pins` — the axes your ROOT `ActiveEidos` nailed, if any
  (`ActiveEidos.create({ mode: 'dark' })` is a nailed instance, not a
  preference). A pin wins over the resolved preference on both sides, so a
  site that nails an axis and does not repeat it here paints the user's
  preference before hydration and swaps to the pin after it — this section's
  flash, inverted. Nothing pinned, nothing to pass.

```ts
renderUixBootScript({
	defaultLocale: 'es',
	themeIds: eidos.listThemes(),
	pins: { mode: 'dark' }
});
```

Pass `storageKey` as well if you replaced the canonical persistence adapter
(`prefs: { storage }`) with one that writes somewhere else. Key and adapter
move together or the two readers stop agreeing.

`nonce` has its own section above, and `artifact` is for a site that compiles a
narrower boot of its own: it replaces the framework's `{ script, hash }` pair,
through the same function, so the hash in your CSP and the body in your page can
never come from two places.

**In development, the root tells you when the two disagree.** `createActiveUix`
reads what the boot stamped on `<html>` before its own projection writes, reads
it again when the turn is over, and names the axis that moved through the
logger. A forgotten `pin`, a `themeIds` missing a family, a `storageKey` that
does not match the adapter, an artifact that lags the schema and a tag the CSP
blocked all produce the same mute flash otherwise. It measures and changes
nothing, and it is silent on a site that never added the tag.

### The declared limit

The boot reproduces the DEFAULT theme resolution (`resolveThemeId`: registered
id → as written; already mode-qualified → as written; otherwise
`${theme}-${mode}`). An app that passes its own `themeResolver` to
`ActiveEidos` has replaced that function, and the compiled boot cannot know
it: `data-theme` will differ until hydration. Such an app owns its own
pre-paint stamp.