Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

UI SDK Docs Improvements (#150)

qaifi-tfebaeb9f135d4
diff --git a/docs/ui-sdk/concepts/agent-modes.mdx b/docs/ui-sdk/concepts/agent-modes.mdx
new file mode 100644
index 000000000..8d91226ef
--- /dev/null
+++ b/docs/ui-sdk/concepts/agent-modes.mdx
@@ -0,0 +1,65 @@
+---
+title: "Agent modes"
+description: "Choose between a fixed agent, a library, a composer, or both."
+---
+
+`agentConfig` decides which agent-selection affordances the shell exposes.
+
+```ts
+type AgentConfig =
+ | { mode: "SingleAgent"; name: string }
+ | { mode: "AgentLibrary" }
+ | { mode: "AgentComposer"; defaultAgentSpec?: AgentSpec }
+ | { mode: "AgentLibraryWithComposer"; defaultAgentSpec?: AgentSpec };
+```
+
+The default is `{ mode: "AgentLibraryWithComposer" }`.
+
+| Mode | Library | Composer | New chat |
+| --- | --- | --- | --- |
+| `SingleAgent` | — | — | yes |
+| `AgentLibrary` | yes | — | no |
+| `AgentComposer` | — | yes | yes |
+| `AgentLibraryWithComposer` | yes | yes | yes |
+
+<AccordionGroup>
+ <Accordion title="SingleAgent">
+ Pins the UI to one named agent. All selection controls are hidden and the user cannot switch agents or open the composer.
+ </Accordion>
+
+ <Accordion title="AgentLibrary">
+ Users pick from agents your `searchAgents` implementation returns, but cannot author a new one. Note that "new chat" is disabled in this mode only.
+
+ <Frame caption="The Agents Library: users pick from the agents your `searchAgents` returns.">
+ ![The Agents Library dialog listing saved agents to choose from](/images/agent-registry.png)
+ </Frame>
+ </Accordion>
+
+ <Accordion title="AgentComposer">
+ Users assemble an ad-hoc agent — model, skills, MCP servers — without browsing a library, and can save it back to the library.
+
+ <Frame caption="Composing an agent — pick a model, add connectors and skills, then save it to the library.">
+ <div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.46", padding: "40px 0" }}>
+ <iframe src="https://app.supademo.com/embed/cmsk13xio00k81p0j1wj6amj6?embed_v=2&utm_source=embed" loading="lazy" title="Compose an agent in TrueForge" allow="clipboard-write" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }} />
+</div>
+ </Frame>
+ </Accordion>
+
+ <Accordion title="AgentLibraryWithComposer">
+ Both surfaces, and the default. Users can pick an existing agent or author a new one.
+ </Accordion>
+</AccordionGroup>
+
+## Gotchas
+
+<Warning>
+ `defaultAgentSpec` seeds a new draft rather than binding to the current one. Changing it does not alter the conversation on screen, and it does not apply on **clear chat** either — that path deliberately preserves the spec already bound to the draft. The new value is picked up when a **new chat** starts. To apply it immediately, remount the component with a new `key`. It is ignored entirely in `SingleAgent` mode.
+</Warning>
+
+<Warning>
+ Always pass an explicit `defaultAgentSpec` in composer modes. Omitting it falls back to `{ model: { name: "openai-main/gpt-4.1" } }`, and requests fail if your backend does not expose a model under that exact name.
+</Warning>
+
+## Settings
+
+The settings panel appears only when your server exposes a `catalog`. Without one it is silently absent — there is no error, so an unexpectedly missing settings button usually means the catalog is not attached. Note that `useCatalogServer()` throws when there is no catalog; use `useOptionalCatalogServer()` in code that must tolerate its absence.
\ No newline at end of file
diff --git a/docs/ui-sdk/get-started/quickstart.mdx b/docs/ui-sdk/get-started/quickstart.mdx
index df1c3ece3..a98825a27 100644
--- a/docs/ui-sdk/get-started/quickstart.mdx
+++ b/docs/ui-sdk/get-started/quickstart.mdx
@@ -1,13 +1,13 @@
---
title: "Quickstart"
-description: "Render a working agent chat UI against one of three backends."
+description: "Render a working agent chat UI"
---
## Installation
<CodeGroup>
-```text npm
+```shellscript npm
npm install @truefoundry/trueforge-ui
```
@@ -16,11 +16,12 @@ pnpm add @truefoundry/trueforge-ui
```
```text yarn
+yarn add @truefoundry/agent-ui-sdk
```
</CodeGroup>
-`react` and `react-dom` are required peer dependencies and must be version 18 or 19. `@assistant-ui/core`, `@assistant-ui/react`, and `@types/react` are optional peers, you need to install them yourself only if you use their APIs directly or need to pin a version.
+`react` and `react-dom` are required peer dependencies and must be version 18 or 19.
## Connect with TrueForge Server
@@ -36,62 +37,12 @@ Typed for hosts adopting the harness adapter.
/>
```
+## Rendered UI
+
<Frame caption="What `TrueforgeUI` renders — a full agent chat with streaming, history, and tool calls.">
![The TrueforgeUI component rendering an agent chat with an agent-steps panel and a streamed response](/images/landing-screen.png)
</Frame>
-
-## Troubleshooting
-
-<AccordionGroup>
- <Accordion title="Error: requires an AuiProvider">
- Deduplicate the assistant-ui singletons `react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of _"requires an AuiProvider"_.
-
- <CodeGroup>
-
- ```ts vite.config.ts
- export default defineConfig({
- resolve: {
- dedupe: [
- "react",
- "react-dom",
- "@assistant-ui/core",
- "@assistant-ui/react",
- "@assistant-ui/store",
- ],
- },
- });
- ```
-
- ```json package.json
- {
- "resolutions": {
- "@assistant-ui/core": "<version>",
- "@assistant-ui/store": "<version>"
- }
- }
- ```
-
- </CodeGroup>
-
- The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.
-
- Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves `@assistant-ui/core` against.
- </Accordion>
-
- <Accordion title="The UI renders but is collapsed to zero height">
- The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.
-
- ```tsx
- <div className="flex h-dvh min-h-0 w-full flex-1 flex-col">
- <TrueforgeUI /* ... */ className="h-full min-h-0" />
- </div>
- ```
-
- The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.
- </Accordion>
-</AccordionGroup>
-
## Where to go next
<CardGroup cols={2}>
diff --git a/docs/ui-sdk/guides/layouts.mdx b/docs/ui-sdk/guides/layouts.mdx
index 17fcbfe27..0f46facfc 100644
--- a/docs/ui-sdk/guides/layouts.mdx
+++ b/docs/ui-sdk/guides/layouts.mdx
@@ -3,42 +3,40 @@ title: "Layouts"
description: "The four built-in layouts, and how to supply your own."
---
-`layout` is required. Pass one of the built-in names or your own component.
+The sidebar view is the default option. You can pass predefined values - sidebar, drawer, dock, or widget to change the layout.
<Tabs>
- <Tab title="sidebar">
- Full-page chat with a persistent thread list on the left. The default choice for a
- dedicated chat surface.
+ <Tab title="sidebar(default)">
+ Full-page chat with a persistent chat history on the left. The default choice for a dedicated chat surface.
```tsx
<TrueforgeUI server={server} layout="sidebar" />
```
<Frame caption="Sidebar: full-page chat with the thread list pinned on the left.">
- <img src="/images/sidebar.png" alt="Sidebar layout — a persistent thread list on the left beside a full-page chat" />
+ ![Sidebar layout — a persistent thread list on the left beside a full-page chat](/images/sidebar.png)
</Frame>
</Tab>
<Tab title="drawer">
- Thread list collapses into an overlay drawer. Suited to narrower viewports.
+ Chat history list collapses into an overlay drawer. Click on the history icon to view the past conversations. Suited to narrower viewports.
```tsx
<TrueforgeUI server={server} layout="drawer" />
```
<Frame caption="Drawer: the thread list collapses into an overlay for narrow viewports.">
- <img src="/images/drawer.png" alt="Drawer layout — the thread list collapsed into an overlay drawer" />
+ ![Drawer layout — the thread list collapsed into an overlay drawer](/images/drawer.png)
</Frame>
</Tab>
<Tab title="dock">
- A panel pinned to the right edge, filling the available width up to a 400px cap. The side is
- not configurable.
+ A panel pinned to the right edge, filling the available width up to a 400px cap.
```tsx
<TrueforgeUI server={server} layout="dock" />
```
<Frame caption="Dock: a compact panel pinned to the right edge, up to a 400px cap.">
- <img src="/images/dock.png" alt="Dock layout — a compact chat panel pinned to the right edge of the app" />
+ ![Dock layout — a compact chat panel pinned to the right edge of the app](/images/dock.png)
</Frame>
</Tab>
<Tab title="widget">
@@ -49,73 +47,9 @@ description: "The four built-in layouts, and how to supply your own."
```
<Frame caption="Widget: a floating launcher that expands into a compact chat panel.">
- <img src="/images/widget.png" alt="Widget layout — a floating launcher expanded into a compact chat panel" />
+ ![Widget layout — a floating launcher expanded into a compact chat panel](/images/widget.png)
</Frame>
</Tab>
</Tabs>
-Built-in layouts are code-split, so naming one does not pull the other three into your bundle.
-A placeholder renders for the moment it takes to load.
-
-`dock` and `widget` are compact layouts: rather than showing the thread list beside the
-conversation, they stack the two and let the user switch between them from a history control.
-`sidebar` and `drawer` keep the list available alongside the chat.
-
-## Custom layouts
-
-Pass a component instead of a string. It renders inside the full provider stack, so every
-container hook and `useSlot` lookup works normally.
-
-```tsx
-import { Thread, ThreadListContainer, TrueforgeUI } from "@truefoundry/trueforge-ui";
-
-function MyLayout() {
- return (
- <div className="flex h-full min-h-0">
- <aside className="w-72 shrink-0 border-r">
- <ThreadListContainer />
- </aside>
- <main className="min-h-0 flex-1">
- <Thread />
- </main>
- </div>
- );
-}
-
-<TrueforgeUI server={server} layout={MyLayout} />;
-```
-
-<Frame caption="A custom layout renders inside the full provider stack, so every container hook still works.">
- <img src="/images/custom.png" alt="A custom TrueForge layout composed from a thread list and a chat pane" />
-</Frame>
-
-`Thread` is a convenience wrapper equal to
-`<ThreadContainer composer={<ComposerContainer />} />`. Split them apart when you need the
-composer somewhere other than directly beneath the transcript.
-
-<Warning>
- The settings panel is part of the built-in layouts, so a custom layout does not get one. If
- you need settings, either stay on a built-in layout or build your own panel against the
- `catalog` server — see [Server](/ui-sdk/reference/server).
-</Warning>
-
-## Composing without TrueforgeUI
-
-For maximum control, mount the providers yourself. Order matters — `SlotsProvider` must be
-outside `TrueFoundryChatProvider`.
-
-```tsx
-<SlotsProvider overrides={overrides} theme={theme}>
- <ServerProvider server={server}>
- <ShellModeProvider agentConfig={{ mode: "AgentLibrary" }}>
- <TrueFoundryChatProvider server={server}>
- <MyLayout />
- </TrueFoundryChatProvider>
- </ShellModeProvider>
- </ServerProvider>
-</SlotsProvider>
-```
-
-This path gives up the automatic runtime reset that `TrueforgeUI` performs when the selected
-agent changes, so you become responsible for remounting `TrueFoundryChatProvider` — change its
-`key` — at those moments.
+Built-in layouts are code-split, so using one does not pull the other three into your bundle. A placeholder renders for the moment it takes to load.
\ No newline at end of file
diff --git a/docs/ui-sdk/guides/theming.mdx b/docs/ui-sdk/guides/theming.mdx
index c47ffde82..d3dbbbdf1 100644
--- a/docs/ui-sdk/guides/theming.mdx
+++ b/docs/ui-sdk/guides/theming.mdx
@@ -1,11 +1,9 @@
---
-title: "Theming"
-description: "Presets, semantic tokens, branding, and dark mode."
+title: "Preset Themes"
+description: "Presets, branding, and dark mode."
---
-Theming works the way shadcn/ui theming works: semantic tokens compiled to CSS custom
-properties. `ThemeProvider` writes them as inline styles on a wrapper `div.aui-theme-root`,
-tagged with `data-theme` and `data-preset`.
+You can choose from four preset themes - Claude, ChaptGPT, Gemini, or TrueFoundry
## The theme object
@@ -13,22 +11,24 @@ tagged with `data-theme` and `data-preset`.
type ThemeConfig = {
preset?: "truefoundry" | "claude" | "chatgpt" | "gemini"; // default "truefoundry"
mode?: "light" | "dark" | "system";
- tokens?: Partial<SemanticTokens>;
- brand?: BrandConfig;
- className?: string;
- icons?: IconMap;
- classNames?: ContentClassNames;
+ brand?: {
+ name?: string;
+ logo?: string | BrandLogo;
+ },
+ ...
};
```
-```tsx
+```tsx App.tsx
<TrueforgeUI
- server={server}
- layout="sidebar"
+ ...
theme={{
preset: "claude",
- tokens: { primary: "#0B5FFF", composerRadius: "1rem" },
- brand: { name: "Acme", icon: { src: "/logo.svg", alt: "Acme" } },
+ mode: "system",
+ brand: {
+ name: "TrueForge",
+ logo: "/logo.svg",
+ }
}}
/>
```
@@ -37,116 +37,43 @@ The `chatgpt`, `claude`, and `gemini` presets (the default is `truefoundry`):
<Columns cols={3}>
<Frame caption="chatgpt">
- <img src="/images/theme-chatgpt.png" alt="TrueForge UI with the chatgpt theme preset" />
+ ![TrueForge UI with the chatgpt theme preset](/images/theme-chatgpt.png)
</Frame>
+
<Frame caption="claude">
- <img src="/images/theme-claude.png" alt="TrueForge UI with the claude theme preset" />
+ ![TrueForge UI with the claude theme preset](/images/theme-claude.png)
</Frame>
+
<Frame caption="gemini">
- <img src="/images/theme-gemini.png" alt="TrueForge UI with the gemini theme preset" />
+ ![TrueForge UI with the gemini theme preset](/images/theme-gemini.png)
</Frame>
</Columns>
-## Precedence
-
-The provider resolves the preset for the current mode, merges your `theme.tokens` over it, and
-writes the result as **inline styles** on the theme root. So within `theme.tokens`, your entries
-beat the preset — that part is straightforward.
-
-<Warning>
- Because those tokens land as inline styles, a `:root { --primary: … }` rule in your own CSS
- will **not** override them. This applies to every token a preset defines, whether or not you
- passed `theme.tokens`. Use `theme.tokens` to change these, not CSS.
-</Warning>
-
-A few tokens are absent from the presets — `scrollbarThumb`, `assistantBubble`, and
-`assistantBubbleForeground`. Those are not written inline unless you set them, so they fall
-through to the stylesheet's low-precedence layer and a host `:root` rule does take effect.
-
-`theme.className` is applied to the theme root, for utility-class adjustments alongside the
-tokens.
-
-<Note>
- `brand`, `icons`, and `classNames` are not part of this cascade — they are separate context
- values, not tokens that layer over one another.
-</Note>
-
## Light and dark mode
-Omit `theme.mode` and the provider is uncontrolled: it resolves `system`, lets the user
-toggle, and persists the choice to `localStorage` under `aui-theme-preference`. Pass
-`theme.mode` and the provider becomes controlled — `setTheme` from `useTheme()` becomes a
-no-op and you own the state.
+Skip means defaults to system theme. User can choose via UI.
-<Warning>
- Dark mode toggles the `dark` class on `document.documentElement`. If your app already
- manages dark mode by the same mechanism, the two will fight. Pass a controlled
- `theme.mode` derived from your own state to keep them in sync.
-</Warning>
+Pass to set a theme to light, dark or system. User CANNOT update it. This is useful when you want to control the theme based on the main/top level app theme.
<Frame caption="Dark mode applied to the chat UI.">
- <img src="/images/dark_theme.png" alt="The TrueForge UI SDK rendered in dark mode" />
+ ![The TrueForge UI SDK rendered in dark mode](/images/dark_theme.png)
</Frame>
-## Reading theme state
-
-```tsx
-import { useTheme, useThemeMode, useBrand } from "@truefoundry/trueforge-ui";
-
-const { preset, mode, preference, isDark, setTheme } = useTheme();
-const resolved = useThemeMode(); // "light" | "dark", defaults to "light" outside a provider
-const brand = useBrand();
-```
-
-`BrandLogo` and `BrandIcon` render `theme.brand.logo` and `theme.brand.icon`. Their fallbacks
-differ: `BrandLogo` falls back to a default mark plus the brand name (default `"TrueFoundry"`),
-while `BrandIcon` falls back to the bare mark with no name.
-
-## Token naming
-
-`SemanticTokens` keys map to the kebab-cased CSS variable of the same name — `cardForeground`
-becomes `--card-foreground`, `composerRadius` becomes `--composer-radius`, `scrollbarThumb`
-becomes `--scrollbar-thumb`.
-
-One token breaks that rule:
-
-| Token | CSS variable |
-| --- | --- |
-| `fontFamily` | `--font-agent-ui` |
-
-Alongside the usual surface and text tokens, the palette includes status pairs for
-`destructive`, `success`, and `warning`, each with a matching `*Foreground`.
+### Set separate logo for light and dark theme
-<Note>
- `theme.tokens` is a `Partial`, so you only supply the tokens you want to change and the preset
- fills in the rest. The status pairs matter only if you construct a complete `SemanticTokens`
- object — for instance when building your own preset — in which case all four of `success`,
- `successForeground`, `warning`, and `warningForeground` are required.
-</Note>
-
-## Styling rendered content
-
-`theme.classNames` targets the content renderers:
-
-```ts
-type ContentClassNames = {
- markdown?: string;
- inlineCode?: string;
- syntaxHighlighter?: { root?: string; pre?: string; code?: string; lineNumber?: string };
- openui?: { root?: string; scope?: string };
- monaco?: { root?: string };
-};
-```
-
-For CSS-only adjustments you can instead target the stable class names directly:
-`.aui-markdown`, `.aui-syntax-highlighter`, `.aui-openui`, `.aui-monaco`.
-
-## Presets
-
-```ts
-import { PRESETS, resolvePresetTokens } from "@truefoundry/trueforge-ui";
-
-const tokens = resolvePresetTokens("gemini", "dark");
-```
-
-`PRESETS` is a `Record<ThemePreset, { light, dark }>` — useful for building a preset picker.
+```tsx App.tsx
+<TrueforgeUI
+ ...
+ theme={{
+ ...
+ brand: {
+ name: "TrueForge",
+ logo: {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg",
+ "href": "https://trueforge.dev" //URL to redirect on logo click
+ },
+ }
+ }}
+/>
+```
\ No newline at end of file
diff --git a/docs/ui-sdk/guides/troubleshooting.mdx b/docs/ui-sdk/guides/troubleshooting.mdx
index 3c245cce3..ff4f88bef 100644
--- a/docs/ui-sdk/guides/troubleshooting.mdx
+++ b/docs/ui-sdk/guides/troubleshooting.mdx
@@ -5,78 +5,91 @@ description: "Common failure modes and their causes."
<AccordionGroup>
<Accordion title="Error: requires an AuiProvider">
- Two copies of an assistant-ui package are in the bundle. Deduplicate `react`,
- `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` — see
- [Installation](/ui-sdk/get-started/installation).
+ Deduplicate the assistant-ui singletons `react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of _"requires an AuiProvider"_.
+
+ <CodeGroup>
+
+ ```ts vite.config.ts
+ export default defineConfig({
+ resolve: {
+ dedupe: [
+ "react",
+ "react-dom",
+ "@assistant-ui/core",
+ "@assistant-ui/react",
+ "@assistant-ui/store",
+ ],
+ },
+ });
+ ```
+
+ ```json package.json
+ {
+ "resolutions": {
+ "@assistant-ui/core": "<version>",
+ "@assistant-ui/store": "<version>"
+ }
+ }
+ ```
+
+ </CodeGroup>
+
+ The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.
+
+ Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves `@assistant-ui/core` against.
</Accordion>
<Accordion title="The UI renders but is collapsed to zero height">
- The SDK fills its parent and sets no height of its own. Give the wrapper a resolved
- height (`h-dvh` plus `min-h-0`, or an explicit pixel height) and pass
- `className="h-full min-h-0"`.
+ The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.
+
+ ```tsx
+ <div className="flex h-dvh min-h-0 w-full flex-1 flex-col">
+ <TrueforgeUI /* ... */ className="h-full min-h-0" />
+ </div>
+ ```
+
+ The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.
</Accordion>
<Accordion title="The SDK renders unstyled">
- Check that `@import "@truefoundry/trueforge-ui/styles.css";` is actually reaching the
- browser — that single import is the entire styling setup, and the stylesheet is
- self-contained. You do not need Tailwind in your own app for the SDK to look right.
+ Check that `@import "@truefoundry/trueforge-ui/styles.css";` is actually reaching the browser — that single import is the entire styling setup, and the stylesheet is self-contained. You do not need Tailwind in your own app for the SDK to look right.
</Accordion>
<Accordion title="Your app's own base styles changed after installing">
- The SDK's stylesheet deliberately omits Tailwind preflight so it cannot reset your styles,
- so this is unlikely to come from the import itself. Look instead at whether you added
- `@import "tailwindcss";` at the same time — that one does ship preflight, and it resets
- host styles by design.
+ The SDK's stylesheet deliberately omits Tailwind preflight so it cannot reset your styles, so this is unlikely to come from the import itself. Look instead at whether you added `@import "tailwindcss";` at the same time — that one does ship preflight, and it resets host styles by design.
</Accordion>
<Accordion title="An error alert appears immediately on mount">
- If you passed `type: "trueforge"`, that is expected — the harness adapter has not shipped,
- so it resolves to a not-implemented error. Use `type: "truefoundry"` or a
- [custom server](/ui-sdk/guides/custom-server) instead.
+ If you passed `type: "trueforge"`, that is expected — the harness adapter has not shipped, so it resolves to a not-implemented error. Use `type: "truefoundry"` or a [custom server](/ui-sdk/guides/custom-server) instead.
- Otherwise the server failed to resolve: check that `apiKey` and `controlPlaneURL` are set
- and reachable. Attach an `onError` handler to see the underlying error.
+ Otherwise the server failed to resolve: check that `apiKey` and `controlPlaneURL` are set and reachable. Attach an `onError` handler to see the underlying error.
</Accordion>
<Accordion title="Requests fail in composer mode with an unknown model">
- Without an explicit `defaultAgentSpec`, drafts default to `openai-main/gpt-4.1`. Pass a
- spec naming a model your backend actually exposes:
- `agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "..." } } }}`.
+ Without an explicit `defaultAgentSpec`, drafts default to `openai-main/gpt-4.1`. Pass a spec naming a model your backend actually exposes: `agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "..." } } }}`.
</Accordion>
<Accordion title="Changing defaultAgentSpec did not affect the open conversation">
- It seeds a new draft rather than binding to the current one, so the change lands on the next
- **new chat**. Clear chat will not pick it up — that path preserves the spec already bound to
- the draft. To apply it to the conversation on screen, remount the component with a new
- `key`. It is ignored entirely in `SingleAgent` mode.
+ It seeds a new draft rather than binding to the current one, so the change lands on the next **new chat**. Clear chat will not pick it up — that path preserves the spec already bound to the draft. To apply it to the conversation on screen, remount the component with a new `key`. It is ignored entirely in `SingleAgent` mode.
</Accordion>
<Accordion title="The settings button is missing">
- Settings render only when your server exposes a `catalog`, so attach one to enable the
- panel. If you are on a custom layout, that is the other cause — the panel ships with the
- built-in layouts only.
+ Settings render only when your server exposes a `catalog`, so attach one to enable the panel. If you are on a custom layout, that is the other cause — the panel ships with the built-in layouts only.
</Accordion>
<Accordion title="Only the OAuth screen renders — no chat">
- A `screenType=mcp-auth` query parameter is present on the URL. `TrueforgeUI` renders the
- OAuth completion screen exclusively in that case. Keep the callback on its own route; see
- [MCP OAuth](/ui-sdk/guides/mcp-oauth).
+ A `screenType=mcp-auth` query parameter is present on the URL. `TrueforgeUI` renders the OAuth completion screen exclusively in that case. Keep the callback on its own route; see [MCP OAuth](/ui-sdk/guides/mcp-oauth).
</Accordion>
<Accordion title="Dark mode fights with the host application">
- The provider toggles the `dark` class on `document.documentElement`. Pass a controlled
- `theme.mode` derived from your own state so the two stay aligned.
+ The provider toggles the `dark` class on `document.documentElement`. Pass a controlled `theme.mode` derived from your own state so the two stay aligned.
</Accordion>
<Accordion title="Import of Button or AskUserPrompt fails">
- A few names are published as types only, so importing them as values fails. `Button` and
- `IconButton` are restyled through [theme tokens](/ui-sdk/guides/theming) rather than replaced.
- `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` are override-only — supply your own
- component typed with the published props.
+ A few names are published as types only, so importing them as values fails. `Button` and `IconButton` are restyled through [theme tokens](/ui-sdk/guides/theming) rather than replaced. `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` are override-only — supply your own component typed with the published props.
</Accordion>
<Accordion title="SSR or React Server Components errors">
- The package is ESM-only and client-only. Mount `TrueforgeUI` from a client component — in
- Next.js App Router, a file with `"use client"` at the top.
+ The package is ESM-only and client-only. Mount `TrueforgeUI` from a client component — in Next.js App Router, a file with `"use client"` at the top.
</Accordion>
-</AccordionGroup>
+</AccordionGroup>
\ No newline at end of file
diff --git a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
index a43be2a9d..1c8acc125 100644
--- a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
+++ b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
@@ -3,109 +3,119 @@ title: "Custom Theme"
description: "Build your own custom theme"
---
-Pass an `overrides` object to replace a built-in component. Your version is used everywhere
-that component appears, without you having to find each place it is rendered.
+## The Theme Object
+
+Theme object supports params to pass `tokens` to override styles of UI components. You can also override app level classes
+
+```jsx App.jsx
+type ThemeConfig = {
+ ...
+ tokens?: Partial<SemanticTokens>;
+ className?: string;
+ icons?: IconMap;
+ classNames?: ContentClassNames;
+};
+```
-```tsx
-import { TrueforgeUI, type AssistantMessageBubbleProps } from "@truefoundry/trueforge-ui";
-
-function MyBubble({ children, error, actionBar, className }: AssistantMessageBubbleProps) {
- return (
- <div className={className} data-testid="my-bubble">
- {error}
- <div className="prose">{children}</div>
- {actionBar}
- </div>
- );
-}
-
-<TrueforgeUI
- server={server}
- layout="sidebar"
- overrides={{ AssistantMessageBubble: MyBubble }}
-/>;
+## The Token Object
+
+```json Token Object
+{
+ background: "#c18585",
+ foreground: "#1f1f1f",
+ card: "#ffffff",
+ cardForeground: "#1f1f1f",
+ popover: "#f0f4f9",
+ popoverForeground: "#1f1f1f",
+ primary: "#1f3b9b",
+ primaryForeground: "#ffffff",
+ secondary: "#e8eaed",
+ secondaryForeground: "#1f1f1f",
+ muted: "#f8fafd",
+ mutedForeground: "#444746",
+ accent: "#e9eef6",
+ accentForeground: "#1f1f1f",
+ destructive: "#b3261e",
+ destructiveForeground: "#ffffff",
+ border: "#dadce0",
+ input: "#dadce0",
+ ring: "#1f3b9b",
+ userBubble: "#f3f6fc",
+ userBubbleForeground: "#1f1f1f",
+ radius: "1rem",
+ composerRadius: "2rem",
+ fontSans: "\"GeistSans\", \"GeistSans Fallback\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif",
+ }
```
-`SlotOverrides` is `Partial<AtomSlots>`, so overrides are type-checked against the default
-component's signature. Import the exported `*Props` type for the slot you are replacing and
-honor the props you receive — several are rendered nodes (`actionBar`, `error`,
-`approvalSlot`) that the container supplies and expects you to place.
-
-## Commonly overridden slots
-
-<AccordionGroup>
- <Accordion title="Messages and content">
- `AssistantMessageBubble`, `UserMessageBubble`, `UserMessageEdit`,
- `UserMessageActionBar`, `MessageActionBar`, `MessageErrorBanner`, `MessageIndicator`,
- `MessageTimestamp`, `MessageGroup`, `Markdown`, `SyntaxHighlighter`, `OpenUiFenceBlock`,
- `CodeEditor`, `MonacoEditorCore`, `WelcomeScreen`.
- </Accordion>
- <Accordion title="Composer">
- `ComposerShell`, `ComposerLeftSection`, `ComposerRightSection`, `ComposerSendButton`,
- `AttachmentCard`, `AttachmentPickerButton`, `AttachmentPreviewDialog`.
-
- The draft composer has its own slots — `DraftComposerLeftSection`,
- `DraftComposerRightSection`, `DraftModelSelector`, and `DraftCompositeSelector` — so you can
- restyle the draft chrome without touching the standard composer.
-
- The two sets interact. In a mutable draft the container substitutes the draft sections
- behind `ComposerLeftSection` / `ComposerRightSection`, but only while those slots are still
- at their defaults. Override either one and yours wins in draft mode too, which means the
- model and composite selectors disappear unless you render them yourself.
- </Accordion>
- <Accordion title="Thread shell and list">
- `ThreadRootShell`, `ThreadViewportShell`, `ThreadComposerAreaShell`,
- `ScrollToBottomButton`, `MessageListSkeleton`, `HistoryLoader`, `ThreadListShell`,
- `ThreadListNewButton`, `ThreadListRow`, `ThreadListRowSkeleton`,
- `ThreadListEmptyState`.
- </Accordion>
- <Accordion title="Tools and prompts">
- `ToolCallCard`, `ToolCallContentBlock`, `ToolApprovalBar`, `ToolGroupCard`,
- `SubAgentCard`, `SandboxToolCallCard`, `SandboxArtifactDownload`, `ChatFileDownload`,
- `AgentStepsCard`, and the prompt slots `AskUserPrompt`, `McpAuthPrompt`, `ReasoningCard`.
- </Accordion>
- <Accordion title="Agent library and shell">
- `AgentsLibrary`, `AgentsLibraryButton`, `SaveAgentButton`, `SelectAgentEmptyState`,
- `ClearChatButton`, `ShellActionsActionSlot`, `Toast`, `ToastStack`, `Accordion`,
- `AccordionSummary`, `AccordionDetails`.
-
- `ShellActionsActionSlot` exists purely to be overridden — it renders nothing by default and
- is the supported place to add your own chrome, such as a logout control, beside the theme
- and settings buttons. Layouts keep it mounted while Settings is open, so state in your
- component survives.
- </Accordion>
-</AccordionGroup>
+## Precedence
-<Note>
- `SlotOverrides` is derived directly from the SDK's default slot table, so autocomplete on the
- `overrides` object is an exact list of what can be overridden — nothing more, nothing less.
-</Note>
+The provider resolves the preset for the current mode, merges your `theme.tokens` over it, and writes the result as **inline styles** on the theme root. So within `theme.tokens`, your entries beat the preset — that part is straightforward.
+
+<Warning>
+ Because those tokens land as inline styles, a `:root { --primary: … }` rule in your own CSS will **not** override them. This applies to every token a preset defines, whether or not you passed `theme.tokens`. Use `theme.tokens` to change these, not CSS.
+</Warning>
+
+A few tokens are absent from the presets — `scrollbarThumb`, `assistantBubble`, and `assistantBubbleForeground`. Those are not written inline unless you set them, so they fall through to the stylesheet's low-precedence layer and a host `:root` rule does take effect.
+
+`theme.className` is applied to the theme root, for utility-class adjustments alongside the tokens.
<Note>
- Some slots are override-only, meaning you supply your own component rather than wrapping a
- default: `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` publish their prop types but
- not the components, and `Accordion`, `AccordionSummary`, and `AccordionDetails` publish
- neither.
+ `brand`, `icons`, and `classNames` are not part of this cascade — they are separate context values, not tokens that layer over one another.
</Note>
+## Reading theme state
+
+```tsx
+import { useTheme, useThemeMode, useBrand } from "@truefoundry/trueforge-ui";
+
+const { preset, mode, preference, isDark, setTheme } = useTheme();
+const resolved = useThemeMode(); // "light" | "dark", defaults to "light" outside a provider
+const brand = useBrand();
+```
+
+`BrandLogo` and `BrandIcon` render `theme.brand.logo` and `theme.brand.icon`. Their fallbacks differ: `BrandLogo` falls back to a default mark plus the brand name (default `"TrueFoundry"`), while `BrandIcon` falls back to the bare mark with no name.
+
+## Token naming
+
+`SemanticTokens` keys map to the kebab-cased CSS variable of the same name — `cardForeground` becomes `--card-foreground`, `composerRadius` becomes `--composer-radius`, `scrollbarThumb` becomes `--scrollbar-thumb`.
+
+One token breaks that rule:
+
+| Token | CSS variable |
+| --- | --- |
+| `fontFamily` | `--font-agent-ui` |
+
+Alongside the usual surface and text tokens, the palette includes status pairs for `destructive`, `success`, and `warning`, each with a matching `*Foreground`.
+
<Note>
- `Button` and `IconButton` publish their prop types for typing your own components. The
- buttons themselves are restyled through semantic tokens and CSS rather than replaced — see
- [Theming](/ui-sdk/guides/theming).
+ `theme.tokens` is a `Partial`, so you only supply the tokens you want to change and the preset fills in the rest. The status pairs matter only if you construct a complete `SemanticTokens` object — for instance when building your own preset — in which case all four of `success`, `successForeground`, `warning`, and `warningForeground` are required.
</Note>
-## Discovering slot names
+## Styling rendered content
-`SlotOverrides` is a mapped type over every slot, so your editor autocompletes the available
-names as you type inside the `overrides` object, and hovering a name shows the component
-signature you need to match. That is the fastest way to find a slot. The groups above list the
-ones most applications touch.
+`theme.classNames` targets the content renderers:
-## Overriding outside TrueforgeUI
+```ts
+type ContentClassNames = {
+ markdown?: string;
+ inlineCode?: string;
+ syntaxHighlighter?: { root?: string; pre?: string; code?: string; lineNumber?: string };
+ openui?: { root?: string; scope?: string };
+ monaco?: { root?: string };
+};
+```
-If you compose providers manually, pass overrides to `SlotsProvider` and keep it outside
-`TrueFoundryChatProvider`:
+For CSS-only adjustments you can instead target the stable class names directly: `.aui-markdown`, `.aui-syntax-highlighter`, `.aui-openui`, `.aui-monaco`.
-```tsx
-<SlotsProvider overrides={{ ThreadListRow: MyRow }}>{/* ... */}</SlotsProvider>
+## Presets
+
+```ts
+import { PRESETS, resolvePresetTokens } from "@truefoundry/trueforge-ui";
+
+const tokens = resolvePresetTokens("gemini", "dark");
```
+
+`PRESETS` is a `Record<ThemePreset, { light, dark }>` — useful for building a preset picker.
+
+Refer to [Building custom theme](/ui-sdk/setup-custom-ui/custom-theme) to build a theme from scratch
\ No newline at end of file
diff --git a/docs/ui-sdk/setup-custom-ui/untitled-page.mdx b/docs/ui-sdk/setup-custom-ui/untitled-page.mdx
new file mode 100644
index 000000000..172e777df
--- /dev/null
+++ b/docs/ui-sdk/setup-custom-ui/untitled-page.mdx
@@ -0,0 +1,54 @@
+---
+title: "Custom Layout"
+---
+
+Define a custom layout but still use the existing components
+
+Pass a component instead of a string. It renders inside the full provider stack, so every container hook and `useSlot` lookup works normally.
+
+```tsx App.tsx
+import { Thread, ThreadListContainer, TrueforgeUI } from "@truefoundry/trueforge-ui";
+
+function MyLayout() {
+ return (
+ <div className="flex h-full min-h-0">
+ <aside className="w-72 shrink-0 border-r">
+ <ThreadListContainer />
+ </aside>
+ <main className="min-h-0 flex-1">
+ <Thread />
+ </main>
+ </div>
+ );
+}
+
+<TrueforgeUI server={server} layout={MyLayout} />;
+```
+
+<Frame caption="A custom layout renders inside the full provider stack, so every container hook still works.">
+ ![A custom TrueForge layout composed from a thread list and a chat pane](/images/custom.png)
+</Frame>
+
+`Thread` is a convenience wrapper equal to `<ThreadContainer composer={<ComposerContainer />} />`. Split them apart when you need the composer somewhere other than directly beneath the transcript.
+
+<Warning>
+ The settings panel is part of the built-in layouts, so a custom layout does not get one. If you need settings, either stay on a built-in layout or build your own panel against the `catalog` server — see [Server](/ui-sdk/reference/server).
+</Warning>
+
+## Composing without TrueforgeUI
+
+For maximum control, mount the providers yourself. Order matters — `SlotsProvider` must be outside `TrueFoundryChatProvider`.
+
+```tsx
+<SlotsProvider overrides={overrides} theme={theme}>
+ <ServerProvider server={server}>
+ <ShellModeProvider agentConfig={{ mode: "AgentLibrary" }}>
+ <TrueFoundryChatProvider server={server}>
+ <MyLayout />
+ </TrueFoundryChatProvider>
+ </ShellModeProvider>
+ </ServerProvider>
+</SlotsProvider>
+```
+
+This path gives up the automatic runtime reset that `TrueforgeUI` performs when the selected agent changes, so you become responsible for remounting `TrueFoundryChatProvider` — change its `key` — at those moments.
\ No newline at end of file