Themes.

How theming works

A theme is nothing more than a bundle of CSS custom properties (--rui-color-primary, --rui-radius-md, …) written onto the <aktion-app> host element. Every component reads those variables, so changing a token reskins the whole tree instantly — without re‑rendering. There are three layers, and they compose:

Because every layer resolves to the same --rui-* variables on one shadow host, themes never leak between embeds and sx keeps tracking the active theme instead of hard‑coding a colour.

Built-in themes

Eleven themes come in the box, under fifteen names. Select one with the theme attribute on the host element — light is the default if you omit it. Switching is instant: only the host's CSS variables change.

Four come in a light and a dark variant, and the bare name means the light one, so theme="shadcn" and theme="shadcn-light" are the same theme. Three of those are faithful re-creations of design systems you already know — shadcn/ui, Material UI and HeroUI. The fourth, Signal, is this library's own: an instrument console for the screens people watch rather than read.

<aktion-app theme="dark"></aktion-app>

An unknown name does not throw — it silently falls back to light, so a typo shows up as "my theme did nothing" rather than a crash.

Renamed in 0.7. modern, glass and corporate were replaced by shadcn, mui and heroui. The old spellings still resolve — the resolver rewrites them, so theme="modern" renders shadcn/ui and the host reports data-rui-theme="shadcn-light" — but they are no longer listed anywhere and will be removed in a future release.

Names retired earlier are gone for good: neon, brutalist and skyline were removed and pastel became soft. Each of those now resolves to light.

What each theme actually changes

Every theme shares the same token names, so a component never has to know which one is active. These are the values that give each theme its character (the -dark variants share their sibling's shape and type and differ only in colour):

Tokens alone cannot say "hover dims instead of recolouring" or "Paper has no border", so shadcn, mui, heroui, signal and soft each also ship a block of theme‑specific CSS on top of their tokens — that is where MUI's uppercase tabs and elevation shadows, HeroUI's opacity hover and offset focus outline, shadcn's segmented tab strip and 3px focus ring, and Signal's graph-paper page, monospace readouts and double-hairline focus ring live. light and dark are purely token‑driven. That distinction matters for how you select a theme.

Fonts a theme brings with it

Selecting a theme by name also loads the web fonts it declares. The four themes that need a specific face each declare their own, because the typeface is half of what makes them recognisable:

builtInThemeFonts = {
  shadcn: { import: ["Geist:400,500,600,700", "Geist Mono:400,500"] },
  mui:    { import: ["Roboto:300,400,500,700", "Roboto Mono:400,500"] },
  heroui: { import: ["Inter:400,500,600,700"] },
  signal: { import: ["IBM Plex Sans:400,500,600,700", "IBM Plex Mono:400,500"] },
  // …the -light and -dark spellings of each declare the same families
}

So <aktion-app theme="mui"> and $theme({ name: "mui" }) both inject one de‑duplicated Google Fonts <link> into document.head before painting the tokens. Without it the theme would render in system-ui and its whole type ladder would be invisible.

Set the theme imperatively too — handy for a user‑facing theme switcher in the host page:

const app = document.querySelector("aktion-app");
app.setTheme("dark");                       // a built-in name
app.setTheme({ colorPrimary: "#7c3aed" });  // flat token overrides

Both calls repaint the base layer, which also resets the per‑response overlay tracker — the next render reapplies any $theme({…}) from the active program on top. This docs site has its own light/dark toggle in the top bar, and the live demos below follow it.

Branding in‑program with $theme({…})

Inside a program, write a bare $theme({…}) statement (anywhere at the top level, alongside your $app(…) root). The runtime writes those tokens to the host and reskins the UI instantly. Tokens live in groups: override just colors.primary and every button, badge, link, and focus ring follows.

$theme({ colors: { primary: "#7c3aed", primaryHover: "#6d28d9" } })
$app(Column([
  Card([
    CardHeader("Purple brand", { subtitle: "Only colors.primary changed" }),
    Row([
      Button("Primary", { variant: "primary" }),
      Button("Ghost", { variant: "ghost" }),
      Badge("New", { tone: "primary" })
    ], { gap: "sm" })
  ])
], { gap: "md" }))

Two tokens changed; everything else — surfaces, type, radii, shadows — still comes from the host theme.

Combine groups. Here colors plus radius give a mint‑accented look with a bigger card radius and fully‑rounded buttons:

$theme({
  colors: { primary: "#0d9488", primaryHover: "#0f766e", accent: "#f59e0b" },
  radius: { md: "18px", button: "999px" }
})
$app(Column([
  Card([
    CardHeader("Mint & rounded"),
    Text("Bigger card radius, pill-shaped buttons."),
    Row([
      Button("Save", { variant: "primary" }),
      Button("Cancel", { variant: "secondary" }),
      Badge("Beta", { tone: "warning" })
    ], { gap: "sm" })
  ])
], { gap: "md" }))

Typography is a group too. Override font.family and font.familyHeading for a different voice — here a serif editorial look with a crimson accent and sharp corners:

$theme({
  colors: { primary: "#dc2626", primaryHover: "#b91c1c" },
  font:   { family: "Georgia, 'Times New Roman', serif", familyHeading: "Georgia, serif" },
  radius: { md: "2px", button: "2px" }
})
$app(Column([
  Card([
    CardHeader("Editorial", { subtitle: "Serif type, crimson accent, sharp corners" }),
    Text("$theme({...}) overrides only the tokens you pass — everything else inherits the host theme."),
    Row([Button("Read more", { variant: "primary" }), Badge("Featured", { tone: "danger" })], { gap: "sm" })
  ])
], { gap: "md" }))

Start from a built‑in palette instead of light by adding the name metadata key. It seeds the full token set from that theme, then your groups layer on top:

$theme({ name: "heroui", colors: { primary: "#0f766e" } })
$app(Column([
  Card([CardHeader("Console", { subtitle: "heroui base, one override" })])
], { gap: "md" }))

An unknown name is ignored and seeds nothing, so the active base theme survives a typo rather than being wiped.

Token group reference

Inside $theme({…}) the top‑level keys are structured groups. Each group's camel‑case keys flatten to a predictable CSS variable: colors.primary → --rui-color-primary, radius.md → --rui-radius-md, font.familyHeading → --rui-font-family-heading. Here is every group:

Two metadata keys are accepted at the top level: name selects one of the six built‑in themes as the base palette before your overrides layer on top, and direction ("ltr"/"rtl") is advisory metadata. Neither is emitted as a CSS variable. Flat keys (colorPrimary) and free‑form CSS variables are dropped at runtime and reported by the schema validator with a migration hint — inside $theme({…}) always use the grouped shape.

$theme({
  fonts: { import: ["Inter:400,600", "Space Grotesk:600"] },
  font: { family: "'Inter', system-ui, sans-serif", familyHeading: "'Space Grotesk', 'Inter', sans-serif" }
})
$app(Text("Corporate-like type", { variant: "title" }))

Colour tokens

The colors group is the one you'll reach for most: 31 keys, of which the light theme sets 28 and derives the last three. Defaults shown are light's.

link, linkHover and surfaceHover are the three optional keys light leaves out: the stylesheet derives them from accent, accentHover and surface. Set them when the derivation is wrong for your palette — soft, mui and heroui all ship an explicit link (HeroUI's #006fee is only 3.8:1 as text on its dark card, so the dark variant's link steps up to #66aaf9), and dark overrides only linkHover because hover has to brighten on a dark surface.

Status colours come in threes

Each status hue is really three tokens, because the same green cannot legally do all three jobs. This is the part of the token set people most often get wrong, so it is worth learning once:

The same triple exists for warning, danger and info. Why it matters numerically: #10b981 measures 2.54:1 on white, so it is a fine bar colour and an illegal text colour — and the stylesheet paints status text in roughly 45 places.

$theme({
  colors: { success: "#0d9488", successText: "#0f766e", onSuccess: "#04291e" }
})
$app(Column([
  Row([Badge("Passing", { tone: "success" }), Pill("SSL active", "success")], { gap: "sm" }),
  Callout("Deploy finished", { tone: "success", description: "All checks green." })
], { gap: "md" }))

All three tokens move together, so the badge text, the pill tint and the callout icon disc all land on the same teal.

borderControl follows the same logic one level up. colors.border is intentionally faint (1.17–1.70:1 in every built‑in theme) because it also draws dividers and table separators; darkening it would make the whole library heavy. colors.borderControl carries the accessible 3:1 boundary for controls a user has to find. Retint both when you rebrand. See Accessibility for the contrast guarantees the themes are tested against.

Radius, spacing, type & shadows

These shape and rhythm tokens drive corner rounding, the spacing scale behind gap/padding props and sx, the type ramp, and elevation. Defaults are from the light theme.

The eight numeric rungs exist so a theme can retune the whole type scale, not just the five named sizes. They carry the values the stylesheet used to hardcode, so adopting them is a visual no‑op until you change one.

spacing advertises t‑shirt names but stores sm/md/lg in the historical short variables, so spacing: { md: "16px" } and spacing: { m: "16px" } both write --rui-spacing-m. The stylesheet also publishes read‑only aliases --rui-spacing-sm|md|lg and --rui-spacing-none: 0px if you need to var() them directly.

The size scale and its legacy spellings

One scale backs every spacing‑ish prop (gap, padding, sx.p, sx.m) and a shorter one backs every component size prop. Six older spellings still work but are no longer advertised in prop enums:

$app(Column([
  Row([
    Button("Small", { size: "sm" }),
    Button("Medium", { size: "md" }),   // md is the default
    Button("Large", { size: "lg" })
  ], { gap: "xs" }),
  Column([Text("3xs gap"), Text("between these")], { gap: "3xs" }),
  Column([Text("2xl gap"), Text("between these")], { gap: "2xl" })
], { gap: "lg" }))

none always resolves to 0, and an unrecognised value falls back to the prop's default rather than leaking through as an unmatched attribute — size: "enormous" renders as md.

Tokens with no $theme route

25 of the 113 tokens have no structured group, because there is no buttons, charts or syntax group to put them in. Passing them inside $theme({…}) does nothing. Reach them with the flat host paths instead:

// Flat keys reach every token, including the 25 with no group.
app.setTheme({ chart1: "#7c3aed", buttonPaddingX: "20px", transitionDuration: "80ms" });

The same map works on the attribute as JSON (theme='{"buttonPaddingX":"20px"}'). If an override of yours is being ignored, check this list first — a groupless token inside $theme({…}) is dropped without an error.

Gradients, fonts & custom icons

Three groups go beyond colours and radii. Gradients are named and reusable, and they power GradientText and the sx.bg: "gradient.brand" intent. Fonts load on demand from a shorthand list. Icons register inline SVG under a name you can use anywhere an icon name is accepted.

Gradients

A gradient value can take three shapes. All three are sanitised before they reach CSS:

$theme({
  gradients: {
    brand: ["#111827", "#7c5cfc"],                            // ≥2 stops → 120deg
    cool: { stops: ["#2563eb", "#22d3ee"], angle: 135 },       // your own angle
    warm: "linear-gradient(90deg, #f59e0b, #ec4899)"           // a raw gradient string
  }
})
$app(Column([
  Display([GradientText("Three gradient shapes", { gradient: "brand" })], { size: "lg" }),
  Row([
    Card([Text("cool")], { sx: { bg: "gradient.cool", p: "lg", radius: "lg", color: "#fff" } }),
    Card([Text("warm")], { sx: { bg: "gradient.warm", p: "lg", radius: "lg", color: "#fff" } })
  ], { gap: "md" })
], { gap: "md" }))

The six gradient names are fixed — brand, accent, warm, cool, success, danger — and light's brand is linear-gradient(120deg, #6366f1 0%, #8b5cf6 50%, #ec4899 100%).

A rejected stop is dropped silently rather than escaping into the stylesheet — see Security for the wider sanitiser story.

Web fonts

Add a fonts group with an import list of "Family:weights" shorthands. Aktion injects one sanitised Google Fonts <link rel="stylesheet">, after which the family is available to font.family:

$theme({
  fonts: { import: ["Inter:400,600,700", "JetBrains Mono", "Inter:400,500i"] },
  font:  { family: "Inter, system-ui, sans-serif", familyMono: "'JetBrains Mono', ui-monospace, monospace" }
})

Weights are optional ("JetBrains Mono" loads the default face) and an i suffix means italic ("Inter:400,500i"). The loader is idempotent and de‑duplicates by URL, so repeating an import across renders costs nothing.

The strict grammar is deliberate: it means a family name coming from model output cannot smuggle a foreign origin or a CSS payload into your page.

Custom icons

Custom icons register inline SVG under a name. Once registered, that name works anywhere an icon name is accepted — the icon prop on Button, Icon("spark"), list bullets, and so on:

$theme({ icons: { spark: "<svg viewBox='0 0 24 24'><path d='M12 2l2 7 7 2-7 2-2 7-2-7-7-2 7-2z'/></svg>" } })
$app(Row([Button("Custom icon", { icon: "spark", variant: "primary" }), Icon("spark")], { gap: "sm" }))

A registered name wins over the Font Awesome lookup, so you can also replace a built‑in icon. Custom SVG is sized to 1em so it matches the surrounding text. The host equivalent is app.registerIcons({…}).

Using theme tokens in your UI

You rarely touch raw colours — components already speak the active theme. When you do need to style something directly, reference tokens through the universal sx prop so it tracks the theme instead of hard‑coding values. Colour tokens (primary, surface, text-muted, …), gradient refs (gradient.brand), spacing tokens (md, lg), and radii all resolve to the same --rui-* variables your theme defines:

$theme({ colors: { primary: "#0d9488" } })
$app(Row([
  Card([Text("Token-styled", { sx: { color: "primary", weight: "700" } })],
    { sx: { bg: "surface", p: "lg", radius: "lg", shadow: "md" } }),
  Card([Text("Gradient bg")],
    { sx: { bg: "gradient.brand", p: "lg", radius: "lg", color: "#fff" } })
], { gap: "md" }))

Because these are tokens, one $theme({…}) override reskins every usage at once. $util.style.token("colors.primary") gives you the same var(--rui-color-primary) string if you need it in an expression. See the sx reference and the universal props reference for the full surface.

Layers, z-index & motion

Two specialised groups make app‑wide behaviour brandable. zIndex tokens feed the sx.zIndex prop and every overlay in the library, so one override re‑orders your whole layering stack:

Five more layer variables exist in the stylesheet but are not themeable, because a program should not be able to reorder them: --rui-z-header: 200, --rui-z-modal-top: 1200 (a dialog that must beat another modal), --rui-z-top: 1600 (lightbox, tour, confetti), --rui-z-skip-link: 1700 and --rui-z-max: 2147483000. zIndex: { header: … } is silently dropped.

motion tokens brand durations and easing. They are optional, and set only by the three framework themes — shadcn 100/150/300ms on cubic-bezier(0.4, 0, 0.2, 1), MUI 150/250/300ms on the same curve, HeroUI 150/250/300ms on cubic-bezier(0, 0, 0.2, 1); when a token is absent, components fall back to their built‑in timings.

$theme({
  zIndex: { modal: 2000, toast: 2100 },
  motion: { fast: "100ms", base: "160ms", slow: "260ms", ease: "cubic-bezier(.2,.8,.2,1)" }
})

The four keys are fast, base, slow and ease — motion.duration is not one of them and does nothing. The related transitionDuration token (the shared hover/focus timing, 120ms) has no group either; set it flat.

Per-response vs host theme

The layers compose cleanly. The host sets a base with the theme="…" attribute (one of the six built‑ins, or a flat JSON token map) or with setTheme(). A program then layers a per‑response overlay by writing a bare $theme({…}) statement — it applies only the tokens you pass, so everything else still inherits the host theme.

Delete the $theme line and the UI snaps straight back to the base with no reload: the overlay's keys are tracked and cleared before every render. Repainting the base (changing the attribute, or calling setTheme()) resets that tracker, and the next render reapplies the overlay on top. Because everything is scoped to one <aktion-app> shadow host, themes never leak across embeds or responses.

Host and JavaScript API

Everything above is reachable from the host page. These are the attributes and methods that matter for theming, plus the exported helpers if you are building your own theme tooling.

import type { ThemeTokens } from "aktion-runtime";

const app = document.querySelector("aktion-app")!;
app.setTheme("mui-dark");                                      // built-in name
app.setTheme({ colorPrimary: "#7c3aed", chart1: "#7c3aed" });  // flat keys reach chart*/button*/hl*

The bundle also exports the theme primitives themselves, so a theme editor or a design‑token pipeline can use the same code paths the element does:

Server‑side rendering does not emit token variables: renderToString has no theme layer, so the browser element applies them on hydration.

tone vs variant

Two prop vocabularies show up all over the library, and they are aliases of each other almost everywhere. tone means semantic colour (success, warning, danger, …) and variant means visual style (outline, ghost, elevated, …). 44 of the 282 components declare one or both.

$app(Row([
  Badge("Live", { variant: "success" }),      // variant → the tone slot
  Button("Save", { tone: "primary" }),        // tone → the variant slot
  Callout("Deployed", { variant: "success" })
], { gap: "sm" }))

All three validate and render: every tone prop carries variant as an alias and vice versa, so guessing the other spelling is no longer a hard error. The alias never invents enum values, though — Button still rejects variant: "success" because success is not one of its variants.

$app(Column([
  Text("Caption", { variant: "small", tone: "muted" }),
  Text("Section title", { variant: "heading" })
], { gap: "xs" }))

Dark mode

There is a first‑class built‑in dark theme — no token authoring required. Set it on the host and your whole tree picks up the dark surfaces, text, borders, shadows and the One Dark syntax palette:

<aktion-app theme="dark"></aktion-app>

Layer a per‑response $theme({…}) on top of dark to brand it — e.g. override colors.primary while keeping the dark surfaces underneath. To follow the OS preference, read it in the host page and call app.setTheme(prefersDark ? "dark" : "light"). Neither theme has a per‑theme CSS block, so this is one of the two cases where $theme({ name: "dark" }) is equivalent to the attribute.

Right-to-left & direction

Theming and layout are direction‑aware. Set dir="rtl" (or "auto") on <aktion-app> to flip the whole tree; logical sx props like px/mx and ps/pe mirror automatically. The direction key inside $theme({…}) is advisory metadata only — use the dir attribute to actually flip the layout.

<aktion-app theme="light" dir="rtl"></aktion-app>

Next