@kitn.ai/chat/src/stories/docs/Theming.mdx

Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS.

import { Meta, Canvas } from '@storybook/addon-docs/blocks';
import * as TokenRef from '../token-reference.stories';

<Meta title="Theming/Overview" />

# Theming

The kit's appearance is driven entirely by **CSS custom properties** (`--color-*` design tokens) defined in `theme.css`. Override them to rebrand everything — buttons, bubbles, borders, the sidebar, code blocks — without touching component code.

## Overriding tokens

Because inherited CSS pierces the Shadow DOM boundary, setting tokens on `:root` re-themes both the SolidJS components and the web components:

```css
:root {
  --color-background: #0f0f0f;
  --color-foreground: #f5f5f5;
  --color-primary: #7c3aed;
  --color-primary-foreground: #ffffff;
  --color-muted: #1e1e1e;
  --color-border: #2a2a2a;
}
```

Scope the same variables to a parent element instead of `:root` to theme just one subtree. The tokens follow the **shadcn/ui convention**: they're *semantic* (`--color-primary`, not `--color-blue`) and come in **`X` / `X-foreground` pairs** — a surface color and the text color that sits on it.

## Live editor

Edit every token for **light and dark** modes and watch a real chat UI re-skin live — pick a preset, tweak swatches, then **Copy CSS** for a paste-ready `:root` + `.dark` block.

<a
  href="?path=/story/theming-editor--editor"
  style={{
    display: 'inline-block',
    background: 'var(--color-primary, #18181b)',
    borderRadius: 'var(--radius-md, 0.5rem)',
    padding: '0.4rem 0.85rem',
    textDecoration: 'none',
  }}
>
  <span style={{
    color: 'var(--color-primary-foreground, #fafafa)',
    fontWeight: 600,
    fontSize: '0.8125rem',
    lineHeight: 1.3,
  }}>Open the theme editor</span>
</a>

_(Opens full-screen — it needs more room than this docs column.)_

## Token reference

A complete, auto-generated reference of every token you can override — generated live from the loaded CSS, so it never drifts from `theme.css`:

<Canvas of={TokenRef.TokenReference} />

## Dark mode

The kit ships light and dark token sets. Toggle dark mode by adding the `dark` class to a root element (this Storybook's toolbar does exactly that):

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

## Appearance settings

`ChatConfig` (SolidJS) and matching properties on `<kc-chat>` control non-color appearance:

| Setting | Values | Purpose |
| --- | --- | --- |
| `proseSize` | `xs` · `sm` · `base` · `lg` | Text/markdown sizing |
| `codeTheme` | any Shiki theme name | Syntax-highlight theme for code blocks |
| `codeHighlight` | `true` / `false` | Turn code highlighting off entirely (renders plain text, loads no Shiki) |

```tsx
<ChatConfig proseSize="base" codeTheme="github-dark-dimmed">
  {/* ... */}
</ChatConfig>
```

```html
<kc-chat prose-size="base" code-theme="github-dark-dimmed"></kc-chat>
```

That's the whole theming surface — tokens for color, `ChatConfig` for sizing and code. Everything else is encapsulated.