Theming

@threadplane/chat styles everything with CSS custom properties (variables). Every color, radius, font, and spacing value is controlled by a variable prefixed with --tplane-chat-, so matching your app's design system is straightforward.

How Theming Works

Chat components define all design tokens using CSS custom properties on the :host element. The token system supports automatic light/dark switching via prefers-color-scheme and explicit override via a [data-threadplane-chat-theme] attribute.

You don't need to import a stylesheet — each component's encapsulated styles apply the tokens automatically. An optional global stylesheet (@threadplane/chat/chat.css) is there if you want to customize tokens at the :root level.

CSS Custom Properties Reference

Colors

Shape & Layout

Typography

Light and Dark Mode

Tokens default to light values. Dark mode activates automatically when the user's system preference is prefers-color-scheme: dark, unless the host element has data-threadplane-chat-theme="light" set.

The switching logic is:

1. Light variables are applied by default on :host
2. @media (prefers-color-scheme: dark) overrides with dark variables, unless data-threadplane-chat-theme="light" is set
3. [data-threadplane-chat-theme="dark"] forces dark variables regardless of system preference

Customizing the Theme

Override a single token at app root

/* src/styles.css */
:root {
  --tplane-chat-primary: oklch(0.55 0.22 264);
}

Force a theme via attribute

<!-- Force dark mode regardless of system preference -->
<chat data-threadplane-chat-theme="dark" [agent]="agent" />
 
<!-- Force light mode regardless of system preference -->
<chat data-threadplane-chat-theme="light" [agent]="agent" />

Deep override via the optional global stylesheet

Import @threadplane/chat/chat.css in your global styles to get a :root-level baseline you can override. For me, this is the move when I'm theming several token groups at once — the cost is one more global import to keep track of, but you get everything in a single place:

/* src/styles.css */
@import '@threadplane/chat/chat.css';
 
:root {
  --tplane-chat-primary: oklch(0.55 0.22 264);
  --tplane-chat-radius-bubble: 10px;
}

Bridge from your design system

If your app already has design-system tokens, keep those tokens as the source of truth and map them into the chat public API. This gives your app a stable --tplane-chat-* control surface without coupling chat internals to your design-system namespace.

:root {
  /* App-owned design tokens */
  --ds-canvas: #ffffff;
  --ds-surface: #f8fafc;
  --ds-border: #e2e8f0;
  --ds-text-primary: #0f172a;
  --ds-text-muted: #64748b;
  --ds-accent: #2563eb;
  --ds-font-sans: Inter, system-ui, sans-serif;
 
  /* Chat-owned public API */
  --tplane-chat-bg: var(--ds-canvas);
  --tplane-chat-surface: var(--ds-surface);
  --tplane-chat-surface-alt: var(--ds-surface);
  --tplane-chat-separator: var(--ds-border);
  --tplane-chat-text: var(--ds-text-primary);
  --tplane-chat-text-muted: var(--ds-text-muted);
  --tplane-chat-primary: var(--ds-accent);
  --tplane-chat-font-family: var(--ds-font-sans);
}

Use the --tplane-chat-* names at chat boundaries and custom chat-adjacent views. Use your app tokens everywhere else. The bridge is useful because chat token names describe component semantics (primary, surface-alt, separator, radius-bubble) while your design-system tokens can stay product-wide and evolve independently.

Brand Color Example

:root {
  /* Brand blues */
  --tplane-chat-primary: #2563eb;
  --tplane-chat-on-primary: #ffffff;
 
  /* Softer corners */
  --tplane-chat-radius-bubble: 12px;
  --tplane-chat-radius-input: 16px;
 
  /* Wider content area */
  --tplane-chat-max-width: 56rem;
}

Migration from --chat-* Tokens

If you previously customized --chat-* tokens, rename them to --tplane-chat-*. Examples: