Skip to content

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

Updated theme screenshots, restructured custom ui section (#141)

qaifi-tf714b28f068ec
diff --git a/docs/docs.json b/docs/docs.json
index 0414b9c66..976044693 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -88,14 +88,20 @@
"ui-sdk/guides/layouts",
"ui-sdk/guides/theming",
"ui-sdk/guides/agent-modes",
- "ui-sdk/guides/slot-overrides",
- "ui-sdk/guides/mcp-oauth",
+ {
+ "group": "Setup Custom UI",
+ "pages": [
+ "ui-sdk/setup-custom-ui/custom-theme",
+ "ui-sdk/setup-custom-ui/slot-overrides",
+ "ui-sdk/setup-custom-ui/mcp-oauth"
+ ]
+ },
{
"group": "Setup Custom Server",
"pages": [
- "ui-sdk/setup-different-servers/server-contract",
- "ui-sdk/setup-different-servers/custom-server",
- "ui-sdk/setup-different-servers/connect-with-truefoundry"
+ "ui-sdk/setup-custom-servers/server-contract",
+ "ui-sdk/setup-custom-servers/custom-server",
+ "ui-sdk/setup-custom-servers/connect-with-truefoundry"
]
},
"ui-sdk/guides/troubleshooting"
diff --git a/docs/images/theme-chatgpt.png b/docs/images/theme-chatgpt.png
index 5eae2f0d1..810ec3a2a 100644
Binary files a/docs/images/theme-chatgpt.png and b/docs/images/theme-chatgpt.png differ
diff --git a/docs/images/theme-claude.png b/docs/images/theme-claude.png
index 7bb47aaed..0151a25aa 100644
Binary files a/docs/images/theme-claude.png and b/docs/images/theme-claude.png differ
diff --git a/docs/images/theme-gemini.png b/docs/images/theme-gemini.png
index d3a8e62f3..f852d9f69 100644
Binary files a/docs/images/theme-gemini.png and b/docs/images/theme-gemini.png differ
diff --git a/docs/ui-sdk/index.mdx b/docs/ui-sdk/index.mdx
index 482d9836d..e465c5db6 100644
--- a/docs/ui-sdk/index.mdx
+++ b/docs/ui-sdk/index.mdx
@@ -16,10 +16,6 @@ Key Features:
<br />
-<Frame caption="A TrueForge UI chat session — streaming response, agent steps, and tool calls.">
- ![The TrueForge UI SDK rendering an agent chat with an expandable agent-steps panel and a streamed response](/images/hero.png)
-</Frame>
-
## Interactive Controls & Code Examples
The hosted webapp provides an interactive interface for exploring and configuring all available controls and properties.
diff --git a/docs/ui-sdk/setup-different-servers/connect-with-truefoundry.mdx b/docs/ui-sdk/setup-custom-servers/connect-with-truefoundry.mdx
similarity index 100%
rename from docs/ui-sdk/setup-different-servers/connect-with-truefoundry.mdx
rename to docs/ui-sdk/setup-custom-servers/connect-with-truefoundry.mdx
diff --git a/docs/ui-sdk/setup-different-servers/custom-server.mdx b/docs/ui-sdk/setup-custom-servers/custom-server.mdx
similarity index 100%
rename from docs/ui-sdk/setup-different-servers/custom-server.mdx
rename to docs/ui-sdk/setup-custom-servers/custom-server.mdx
diff --git a/docs/ui-sdk/setup-different-servers/server-contract.mdx b/docs/ui-sdk/setup-custom-servers/server-contract.mdx
similarity index 100%
rename from docs/ui-sdk/setup-different-servers/server-contract.mdx
rename to docs/ui-sdk/setup-custom-servers/server-contract.mdx
diff --git a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
new file mode 100644
index 000000000..a43be2a9d
--- /dev/null
+++ b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
@@ -0,0 +1,111 @@
+---
+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.
+
+```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 }}
+/>;
+```
+
+`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>
+
+<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>
+
+<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.
+</Note>
+
+<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).
+</Note>
+
+## Discovering slot names
+
+`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.
+
+## Overriding outside TrueforgeUI
+
+If you compose providers manually, pass overrides to `SlotsProvider` and keep it outside
+`TrueFoundryChatProvider`:
+
+```tsx
+<SlotsProvider overrides={{ ThreadListRow: MyRow }}>{/* ... */}</SlotsProvider>
+```
diff --git a/docs/ui-sdk/guides/mcp-oauth.mdx b/docs/ui-sdk/setup-custom-ui/mcp-oauth.mdx
similarity index 100%
rename from docs/ui-sdk/guides/mcp-oauth.mdx
rename to docs/ui-sdk/setup-custom-ui/mcp-oauth.mdx
diff --git a/docs/ui-sdk/guides/slot-overrides.mdx b/docs/ui-sdk/setup-custom-ui/slot-overrides.mdx
similarity index 100%
rename from docs/ui-sdk/guides/slot-overrides.mdx
rename to docs/ui-sdk/setup-custom-ui/slot-overrides.mdx