Skip to content

Themes and design tokens

A theme owns regions, tokens and personalization; tokens become --kywi-* custom properties emitted per request, with key@breakpoint media overrides.

Only two of a theme's fields are load-bearing at construction: defineTheme throws on a missing name and on an empty regions array. Tokens are optional — a theme with none renders against core's neutral fallbacks.

What a theme carries

A theme is exactly these five fields — there is no stylesheet path, no template list and no layout on it. What a theme draws lives in the layer chain (sites/<site>/themes/<theme>/), keyed by the same name; what it declares lives here.

NameTypeDefaultDescription
namerequiredstring—
The value a site's theme field points at. Empty throws at definition.
regionsrequiredRegionDefinition[]—
The named slots a layout document places sections into. Empty throws. Must be identical across every theme registered under a site in kywi.layers.ts — core asserts that at boot.
tokensThemeTokens—
Five categories of design tokens, emitted as CSS custom properties. Absent means core's neutral fallbacks apply.
personalizationPersonalizationConfig—
Whether the browser personalization runtime loads, plus a consentBanner flag that only tells a startup advisory where to expect the consent banner — it does not switch who renders it.
customAllowedboolean | Partial<Record<category, boolean>>true
A declaration for which categories may take a raw value instead of a token reference — the shipped layout editor does not yet consult it.

The site names the theme, and config owns that

theme is a required string on SiteConfig, not a setting an admin can change. Since 0.23.0 core reconciles the config's sites into kywi_sites by slug at boot and on kywi migrate, overwriting the row's domain, name, defaultLocale and theme from the file. Editing that column is not a way to re-theme a site; the next boot puts it back.

Tokens become --kywi-* custom properties

Each token category maps to one fixed variable prefix, kebab-cased on the way out — so typography's familyBase becomes --kywi-font-family-base (the category and the prefix are deliberately different words). An unrecognised category is not dropped either; it becomes its own kebab-cased prefix, a quiet way to end up with variables nothing styles.

packages/core/src/layout/theme-css.tsts
export const CATEGORY_VAR_PREFIX: Record<string, string> = {
  colors: 'color',
  spacing: 'spacing',
  typography: 'font',
  borderRadius: 'border-radius',
  shadow: 'shadow',
}
kywi.config.tsts
defineTheme({
  name: 'docs',
  regions: [
    { name: 'header', label: 'Header' },
    { name: 'main', label: 'Main Content' },
    { name: 'footer', label: 'Footer' },
  ],
  tokens: {
    colors: {
      primary: '#c1da49',
      'primary-contrast': '#0b100e',
      background: '#f7f8f4',
    },
    spacing: { md: '1rem', xl: '2.5rem', 'xl@mobile': '1.5rem' },
    typography: { familyBase: 'var(--font-plex), sans-serif' },
    borderRadius: { lg: '18px' },
  },
})
what core emits into the page, before the shellcss
:root {
  --kywi-color-primary: #c1da49;
  --kywi-color-primary-contrast: #0b100e;
  --kywi-color-background: #f7f8f4;
  --kywi-spacing-md: 1rem;
  --kywi-spacing-xl: 2.5rem;
  --kywi-font-family-base: var(--font-plex), sans-serif;
  --kywi-border-radius-lg: 18px;
}
@media (max-width: 767px) {
:root {
  --kywi-spacing-xl: 1.5rem;
}
}

key@breakpoint is a media block, not a second variable

Seven breakpoint names are recognised: mobile is the only max-width one (767px and below); sm 640, tablet and md 768, lg 1024, desktop and xl 1280, all min-width. The suffixed key is stripped from the base block and re-emitted inside @media against the same selector, so the override wins by cascade order rather than by a different variable name.

Where the block is emitted, and why you cannot move it

The token block is built inside the layout on every request, keyed on the site the Host header resolved to. A module-scope constant would be evaluated once at import, so every host would serve the first site's palette. It renders outside the shell, next to the dev-only stylesheet sentinel: a templates.shell owns the markup from the wrapper inward and is handed neither, so a project chrome cannot ship an unthemed or silently unstyled site. See The stylesheet layers of a Kywi project for where that block lands in the cascade.

Referring to a token from a layout

Section and module style values accept a category.key reference: spacing.xl resolves to var(--kywi-spacing-xl), while 37px is passed through untouched — see Module properties, theme tokens, style overrides for the editor side of the same mechanism.

customAllowed is a declaration, not a mechanism yet: the shipped props panel renders the token-blind PropField and never consults it, so setting it changes nothing in the editor today — the same gap Module properties, theme tokens, style overrides notes from the authoring side.

personalization.consentBanner is the same kind of declaration: setting it to 'host' only tells the startup advisory not to warn when it scans your content for a cookieConsent module and finds none — it does not change who renders the banner. See Wiring personalization and consent for the actual mechanism.