Theming

Every Asgard component reads its colors from the nearest ThemeProvider. A theme is a plain object of tokens (backgrounds, text, borders, accents, semantic colors, per-component overrides), so you can use a built-in palette or supply your own.

ThemeProvider

The simplest, controlled usage: pass a theme object and the provider renders exactly that.

ThemeProvider, themes, ThemeCssVars, useTheme are exported from both the main entry @ekko/asgard and the @ekko/asgard/theme subpath, import them from either (the ekko init rune -t asgard scaffold uses the main entry).

ThemeProvider has no persistence of its own, it renders the theme you feed it. Persisting the choice (localStorage, a Mimir atom, an ekko:rune store) is the app's job; just feed the saved value back into theme.

Theme your own markup (the CSS-vars bridge)

ThemeProvider themes Asgard components, it does not touch your own header, footer, or hand-written SCSS. If you've hit "I switched theme and Asgard re-themed but my own page chrome didn't," this is why, and <ThemeCssVars/> is the fix.

<ThemeCssVars/> mirrors the active theme onto document.documentElement as CSS custom properties (default prefix --ekko-), so your own SCSS can read the same tokens and re-theme on every switch. It renders nothing and is SSR-safe (the write is a no-op on the server and runs once mounted on the client). Place it inside <ThemeProvider>:

Your app SCSS consumes the mirrored tokens with plain var(...):

When you change the theme prop, <ThemeCssVars/> rewrites the custom properties and every rule above re-themes automatically, no extra wiring.

Custom prefix

Pass prefix to change the CSS-var namespace (e.g. to scope vars to your app):

Imperative escape hatch

For non-React callers, or to apply tokens once outside the component tree, use the imperative helpers (both from @ekko/asgard):

• applyThemeToRoot(theme, prefix?), sets the custom properties on document.documentElement now (no-op

during SSR; default prefix --ekko-).

• themeToCssVars(theme, prefix?), returns the flat { "--ekko-background-primary": "#…", … } record

without touching the DOM, handy if you want to inject the vars yourself.

How tokens map to CSS-var names

Each dotted token path becomes a dash-joined name under the prefix; the name field is excluded. For example:

Built-in palettes

themes (from @ekko/asgard/theme) is a map of ready-made palettes:

There are 26 built-in themes. Each is either dark or light (the page background and every token follow it). The keys, grouped:

Dark (18): dark, dracula, monokai, nord, onedark, solarizedDark, gruvboxDark, tokyoNight, ayuDark, materialDark, catppuccinMocha, githubDark, palenight, rosePine, everforestDark, arctic, ubuntu, linuxMint.

Light (8): light, githubLight, solarizedLight, gruvboxLight, ayuLight, materialLight, catppuccinLatte, everforestLight.

The source of truth is Object.keys(themes). Note the exact casing: onedark (not oneDark), ayuDark/ayuLight (not ayu), materialDark/materialLight, everforestDark/everforestLight, catppuccinMocha/catppuccinLatte. Using a key that isn't in the map yields undefined, which ThemeProvider will not accept.

For a plain light/dark toggle, map your boolean to one dark key and one light key, the theme names themselves are not "dark"/"light" so pick a pair:

Switching theme is just changing which object you pass:

Reading the theme

Inside a component, useTheme() returns the active theme and setters:

useTheme() returns { theme, setTheme, themeName, setThemeName }. It must be called inside a ThemeProvider.

Token reference

A theme is a typed object (Theme, from @ekko/asgard/theme). The token tree below is the source of truth (src/theme/types.ts); the same paths are what <ThemeCssVars/> flattens into CSS variables.

background

text

border

accent

interactive

semantic

components (per-component overrides)

opacity

Custom themes

A theme is just a typed object. Start from a built-in one and override what you need:

Nesting

Providers nest. Wrap a subtree in a second ThemeProvider to theme just that region, handy for a preview pane or a differently-themed panel inside an otherwise neutral app.

Inputs hand you the value, not an event

Asgard inputs are controlled and, by design, call your onChange with the value directly, never a DOM event. Write onChange={(v) => setX(v)}, not onChange={(e) => setX(e.target.value)}. This is uniform across the whole suite. The exact payload per input:

All Asgard inputs hand your onChange the VALUE directly, write onChange={(v) => setX(v)}, not e.target.value. (Button is the exception: it isn't a value input, so its onClick receives the DOM mouse event as usual.)

Buttons and forms

<Button> renders a native <button type="button"> by default, so it will not submit a surrounding form. To make a button submit (or reset) a form, set htmlType:

htmlType accepts 'button' (default), 'submit', or 'reset' and maps directly to the underlying <button type=...>. Because the default is 'button', you don't need a guard against accidental double-submits, an Asgard <Button> only submits when you ask it to.

Server-side rendering

Asgard components render on the server with ekko:rune and hydrate on the client. A few notes:

• Select renders only its trigger button during SSR (the dropdown/listbox opens on interaction), so it is

SSR-safe and hydrates without layout shift.

• The CSS-vars bridge is SSR-safe: <ThemeCssVars/> and applyThemeToRoot are no-ops on the server (no

document) and apply once the client mounts. SSR styling still comes from the components themselves and your initial SCSS.

• Components that need a live DOM at mount, canvas-based pickers (ColorPicker's eyedropper checks

window), and drag-and-drop surfaces (Upload), guard their browser-only paths and light up after hydration. If you wrap such a feature yourself, gate it behind a mounted/isBrowser check rather than reading window/document during render.