Custom Theme

The theme object

Pass design tokens on the theme object to override component styles. You can also override app-level CSS classes for broader layout and styling changes.

App.jsx

type ThemeConfig = {
  ...
  tokens?: Partial<SemanticTokens>;
  ...
};

Pass the theme object on TrueForgeUI:

App.tsx

<TrueForgeUI
  server={server}
  layout="sidebar"
  theme={{
    tokens: {
      primaryButtonBg: "#6366F1",
      userMessageBg: "#6366F1",
      // ...other tokens
    },
  }}
/>

The token object

Override individual design tokens to change colors and other visual properties: sidebar, page background, popups, buttons, inputs, and the rest of the surfaces listed below. Set tokens separately for light and dark mode so both schemes stay consistent without per-component CSS.

The fastest way to try tokens is the UI Config App. Change colors in the preview, then copy the generated config into your app.

Token Object

{
  "light": {
    "sidebarBg": "#FAFAFA",
    "primaryBg": "#FFFFFF",
    "textPrimary": "#18181B",
    "primaryButtonBg": "#6366F1",
    "userMessageBg": "#6366F1"
    // ...others (see the full list below)
  },
  "dark": {
    // ...same tokens as light mode
  }
}

Values above are an example brand override, not the built-in preset defaults.

All tokens

See Token naming for how each key maps to a CSS variable.

Token name	Description
`sidebarBg`	Sidebar, chat history, chat drawer.
`sidebarText`	Labels and icons on sidebar / rail nav buttons.
`topbarBg`	Topbar of all pages.
`primaryBg`	Background color of all pages.
`secondaryBg`	Icon background and secondary navigation
`border`	Dividers and outlines. Panel edges, list rows, cards, and form fields.
`fontFamily`	UI font across the Application
`inputBoxBg`	Input and composer surfaces. Chat composer, search fields, shared text inputs.
`inputBorder`	Borders on text inputs and outline / secondary buttons.
`textPrimary`	Headings, labels, and primary body copy.
`textSecondary`	Muted labels, placeholders, timestamps, and helper text.
`cardBg`	Elevated surfaces. Dialogs, menus, tooltips, settings cards, bottom sheets.
`dropdownSelectedItemBg`	Selected item in a dropdown.
`dropdownSelectedItemText`	Text on selected / active menu and list rows.
`userMessageBg`	User chat message bubble background.
`userMessageText`	User chat message bubble text.
`assistantMessageBg`	Assistant message bubble background (default transparent).
`assistantMessageText`	Assistant chat message text.
`primaryButtonBg`	Primary CTAs. Active settings tabs, widget launcher.
`primaryButtonHover`	Primary button hover fill.
`primaryButtonText`	Primary button label color.
`secondaryButtonBg`	Secondary / outline buttons. Cancel, Configure, and similar actions.
`secondaryButtonHover`	Secondary button hover fill.
`secondaryButtonText`	Secondary button label color.
`ghostButtonBg`	Ghost button background (usually transparent). Icon actions and quiet controls.
`ghostButtonHover`	Ghost button and row hover fill. Message actions, nav hover, menu highlight.
`ghostButtonText`	Ghost button icon and label color.
`successBg`	Success pills, icons, and success card fills.
`successText`	Paired text color for solid success fills.
`failureBg`	Error banners, destructive buttons, validation errors, and denied states.
`failureText`	Text on solid failure / destructive fills.
`warningBg`	Warning pills and status dots. Editing badge, in-progress step indicators.
`warningText`	Text on solid warning pills.
`focusRing`	Focus rings on buttons, inputs, switches, and the composer.
`radius`	Base corner radius for buttons, cards, and controls.
`composerRadius`	Chat composer and user message bubble corner radius.
`overlay`	Modal, drawer, and mobile sidebar backdrops.
`shadowColor`	Elevation shadows for the dock panel and widget popup.
`scrollbarThumb`	Scrollbar thumb in the theme root and scrollable panels.

Token naming

SemanticTokens keys map directly to kebab-cased CSS variables. For example, primaryButtonBg maps to --primary-button-bg, and userMessageText maps to --user-message-text. The only exception is fontFamily, which maps to the --font-agent-ui CSS variable. To apply a brand primary color and font across the SDK, override the matching semantic tokens:

const theme = {
  tokens: {
    primaryButtonBg: "#635BFF",
    primaryButtonHover: "#5147E5",
    primaryButtonText: "#FFFFFF",
    fontFamily: "Inter, sans-serif",
    composerRadius: "12px",
  },
};

Those tokens map to CSS variables:

--primary-button-bg
--primary-button-hover
--primary-button-text
--font-agent-ui
--composer-radius

Changing a few semantic tokens updates the UI consistently without writing component-specific CSS.

Getting Started

TrueForge Harness

SDK

UI Chat

Project

The theme object

The token object

All tokens

Token naming

​The theme object

​The token object

​All tokens

​Token naming

The theme object

The token object

All tokens

Token naming