Theming

Override --color-* design tokens on :root to rebrand every kai-* web component at once. Because inherited CSS pierces the Shadow DOM boundary, a single CSS rule propagates into all components automatically.

How tokens work

The kit’s appearance is driven entirely by CSS custom properties defined in theme.css. Each token follows a semantic naming convention borrowed from shadcn/ui — names describe purpose (--color-primary), not hue (--color-blue) — and surface/text pairs come together:

Token pair	Controls
`--color-background` / `--color-foreground`	Page/chat surface and text
`--color-primary` / `--color-primary-foreground`	Buttons, active states, accents
`--color-secondary` / `--color-secondary-foreground`	Secondary buttons, chips
`--color-muted` / `--color-muted-foreground`	Subdued surfaces and placeholder text
`--color-card` / `--color-card-foreground`	Message bubbles, panels
`--color-border`	Dividers and input outlines
`--color-input`	Input field background
`--color-destructive` / `--color-destructive-foreground`	Error and danger states
`--color-ring`	Focus ring (blue by default for WCAG AA contrast)
`--color-sidebar`	Conversation sidebar background
`--color-code-foreground`	Inline code text and chip accent

Border radii are controlled by --radius (default 0.6rem); --radius-sm, --radius-md, --radius-lg, and --radius-xl derive from it automatically.

Import the stylesheet

The kit injects its own scoped CSS into each component’s Shadow DOM automatically — no import required to get started. Import theme.css only to override tokens:

import '@kitn.ai/ui/theme.css';

Or via CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kitn.ai/ui/theme.css">

Override tokens

Set your overrides on :root after importing theme.css:

:root {
  --color-background: hsl(0 0% 6%);
  --color-foreground: hsl(0 0% 96%);
  --color-primary: hsl(271 91% 65%);
  --color-primary-foreground: hsl(0 0% 100%);
  --color-muted: hsl(0 0% 12%);
  --color-muted-foreground: hsl(0 0% 55%);
  --color-border: hsl(0 0% 16%);
  --color-card: hsl(0 0% 10%);
  --color-card-foreground: hsl(0 0% 96%);
  --radius: 0.5rem;
}

Assign tokens to a container element instead of :root to theme only that section of the page — useful when the kit sits alongside other UI that shouldn’t change.

.my-chat-panel {
  --color-primary: hsl(271 91% 65%);
  --color-background: hsl(0 0% 6%);
}

Dark mode

The kit ships both light and dark token sets. Switch modes by toggling the dark class on <html> (or any ancestor):

document.documentElement.classList.toggle('dark');

The .dark selector in theme.css redefines every --color-* token for dark surfaces. Override inside .dark to customize the dark-mode palette:

:root {
  --color-primary: hsl(271 91% 65%);     /* light mode */
}

.dark {
  --color-primary: hsl(271 91% 75%);     /* dark mode — brighter for contrast */
}

The kit does not automatically apply .dark based on prefers-color-scheme — that decision belongs to the host app. Add the class in response to the media query if you want OS-level sync:

const mq = window.matchMedia('(prefers-color-scheme: dark)');
mq.addEventListener('change', (e) => {
  document.documentElement.classList.toggle('dark', e.matches);
});
document.documentElement.classList.toggle('dark', mq.matches);

Namespaced overrides (`--kai-color-*`)

Every --color-* token resolves through a --kai-color-* alias before falling back to its default. Override the --kai-color-* form to rebrand without importing or redefining the entire theme.css token set:

:root {
  --kai-color-primary: hsl(271 91% 65%);
  --kai-color-primary-foreground: hsl(0 0% 100%);
  --kai-radius: 0.375rem;
}

This is the lightest-weight override path — no stylesheet import needed.

Typography

The kit exposes four namespaced typography tokens. Override them to adjust the size of UI chrome (labels, badges, controls) globally:

Token	Default	Applies to
`--kai-text-caption`	`0.6875rem`	Micro labels, badges, sub-counts
`--kai-text-meta`	`0.75rem`	Controls, toggles, captions
`--kai-text-body`	`0.875rem`	Primary reading text
`--kai-text-title`	`1rem`	Emphasis, headers

:root {
  --kai-text-body: 0.9375rem;   /* bump reading text to 15px */
}

Message and markdown reading size scales separately via the proseSize prop — see Appearance settings below.

Appearance settings

Non-color appearance is controlled by kai-chat attributes (and the matching ChatConfig props in the SolidJS layer):

Setting	Values	Purpose
`proseSize`	`xs` · `sm` · `base` · `lg`	Message / markdown text size
`codeTheme`	any Shiki theme name	Syntax-highlight theme for code blocks
`codeHighlight`	`true` / `false`	Disable code highlighting entirely (no Shiki loaded)

Web component
SolidJS

<kai-chat prose-size="base" code-theme="github-dark-dimmed"></kai-chat>

import { ChatConfig } from '@kitn.ai/ui';

<ChatConfig proseSize="base" codeTheme="github-dark-dimmed">
  {/* your components */}
</ChatConfig>

Token reference

The full list of overridable tokens lives in theme.css (shipped at @kitn.ai/ui/theme.css). For a browser-ready version with :root and .dark blocks pre-separated, use @kitn.ai/ui/theme.tokens.css — it is auto-generated from theme.css and never drifts.