# Themes and design tokens

URL: https://kywi-docs-production.up.railway.app/developing/themes-and-design-tokens
Type: docPage

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.

## 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.

export const CATEGORY_VAR_PREFIX: Record<string, string> = { colors: 'color', spacing: 'spacing', typography: 'font', borderRadius: 'border-radius', shadow: 'shadow', }

## packages/core/src/layout/theme-css.ts

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' }, }, })

## kywi.config.ts

: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; } }

## what core emits into the page, before the shell

## 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.

## A misspelled breakpoint deletes the token

The base pass skips every key containing an `@`, and the media pass skips every suffix that is not one of the seven names. A token written `xl@phone` therefore appears in neither block. Nothing warns, and the variable does not exist at render time — so the rule that reads it falls back to whatever default core's stylesheet supplies.

## 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](/developing/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](/authoring/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](/developing/wiring-personalization-and-consent/) for the actual mechanism.

## Two things the theme block does not do

Per-audience token overrides are not shipped: core exports a merge helper for them that nothing calls, so the layout builds the block from the theme alone. And the CLI's view of a theme is thinner than the app's — the config validator's schema for `themes` is `{ name, regions }`, and it returns the parsed object, so `tokens`, `personalization` and `customAllowed` are stripped from anything that loads your config through `parseKywiConfig`. The running app imports `kywi.config.ts` directly and keeps all five.
