Skip to content

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

updated brand config spec (#174)

sajal-truefoundryde3d9c6f1ebf
diff --git a/docs/ui-sdk/guides/layouts-and-theme.mdx b/docs/ui-sdk/guides/layouts-and-theme.mdx
index fab0e6fa1..da436db30 100644
--- a/docs/ui-sdk/guides/layouts-and-theme.mdx
+++ b/docs/ui-sdk/guides/layouts-and-theme.mdx
@@ -67,8 +67,8 @@ type ThemeConfig = {
preset?: "truefoundry" | "claude" | "chatgpt" | "gemini"; // default "truefoundry"
mode?: "light" | "dark" | "system";
brand?: {
- name?: string;
- logo?: string | BrandLogo;
+ name: string; // required when `brand` is set
+ logo?: string | BrandLogoConfig;
},
...
};
@@ -122,13 +122,24 @@ Pass to set a theme to light, dark or system. User CANNOT update it. This is use
theme={{
...
brand: {
- name: "TrueForge",
- logo: {
- "light": "/logo/light.svg",
- "dark": "/logo/dark.svg",
- "href": "https://trueforge.dev" //URL to redirect on logo click
- },
+ name: "TrueForge",
+ logo: {
+ light: "/logo/light.svg",
+ dark: "/logo/dark.svg",
+ href: "https://trueforge.dev", // URL to redirect on logo click
+ },
}
}}
/>
+```
+
+The source is picked from the resolved mode, so this follows the system theme when `mode` is
+omitted. Set only one of `light` / `dark` and it is used for both modes; use `src` for a
+mode-agnostic mark. `name` labels the image, and the link when `href` is set.
+
+To render a component instead of an image — an inline SVG, an animated mark — override the
+`BrandLogo` slot rather than passing a node through `theme`:
+
+```tsx App.tsx
+<TrueforgeUI ... overrides={{ BrandLogo: MyMark }} />
```
\ No newline at end of file
diff --git a/docs/ui-sdk/reference/theme.mdx b/docs/ui-sdk/reference/theme.mdx
index c6770e9ee..fdcc4bfba 100644
--- a/docs/ui-sdk/reference/theme.mdx
+++ b/docs/ui-sdk/reference/theme.mdx
@@ -9,8 +9,7 @@ description: "Theme provider, hooks, presets, brand, and slots."
| --- | --- |
| `ThemeProvider` | Owns light/dark/system state and injects token CSS variables on a wrapper `div.aui-theme-root`. |
| `SlotsProvider` | Slot override registry. Must sit outside `TrueFoundryChatProvider`. |
-| `BrandLogo` | Renders `theme.brand.logo`; falls back to a default mark plus brand name. Props: `{ className? }`. |
-| `BrandIcon` | Renders `theme.brand.icon`, falling back to the bare default mark — no name. Props: `{ className? }`. |
+| `BrandLogo` | The product mark: renders `theme.brand.logo` for the active mode as an image labelled with `theme.brand.name`, linked when the config sets `href`. Falls back to the default mark. Overridable slot. Props: `{ className? }`. |
| `Icon` | Renders a built-in icon by name, or your replacement when `theme.icons` maps that name. Props: `{ name: string \| readonly string[] } & IconProps`. An array resolves to its **last** element, accommodating Font Awesome-style `["far", "clone"]` tuples; it is not a fallback chain. An unresolved name renders nothing. |
## Hooks
@@ -20,6 +19,7 @@ description: "Theme provider, hooks, presets, brand, and slots."
| `useTheme()` | `{ preset, mode, preference, isDark, setTheme }`. `setTheme` is a no-op when `theme.mode` is controlled. |
| `useThemeMode()` | Resolved `"light" \| "dark"`. Reads the mode published by `SlotsProvider`, so it returns `"light"` when no `SlotsProvider` is above it — even in dark mode. |
| `useBrand()` | The active `BrandConfig`. |
+| `useBrandName()` | `theme.brand.name`, or `"TrueForge"` when unset. Safe outside a provider. |
| `useThemeIcons()` | The `IconMap` from `theme.icons`. |
| `useContentClassNames()` | `theme.classNames`; throws outside a provider. |
| `useOptionalContentClassNames()` | Same, but returns `{}` outside a provider instead of throwing — no null check needed. |
@@ -35,7 +35,7 @@ description: "Theme provider, hooks, presets, brand, and slots."
## Types
-`ThemeConfig`, `ThemeMode`, `ThemePreset`, `SemanticTokens`, `BrandConfig`, `BrandImage`,
+`ThemeConfig`, `ThemeMode`, `ThemePreset`, `SemanticTokens`, `BrandConfig`, `BrandLogoConfig`,
`ContentClassNames`, `IconMap`, `ThemeIconProps`, `IconProps`, `LayoutProp`, `AtomSlots`,
`SlotOverrides`.
diff --git a/docs/ui-sdk/reference/trueforge-ui.mdx b/docs/ui-sdk/reference/trueforge-ui.mdx
index d03b03a6c..419f83c0c 100644
--- a/docs/ui-sdk/reference/trueforge-ui.mdx
+++ b/docs/ui-sdk/reference/trueforge-ui.mdx
@@ -116,19 +116,36 @@ import { TrueforgeUI } from "@truefoundry/trueforge-ui";
</Expandable>
</ParamField>
<ParamField path="brand" type="BrandConfig">
+ Optional. Omit it to keep the default mark and the `"TrueForge"` name; setting it
+ requires a `name`.
+
<Expandable title="BrandConfig">
- <ParamField path="logo" type="BrandImage">
- Falls back to the default mark plus the brand name.
+ <ParamField path="name" type="string" required>
+ Shown beside the mark, and used as the logo's accessible label.
+ </ParamField>
+ <ParamField path="logo" type="string | BrandLogoConfig">
+ Image URL, or per-mode sources. Omit to pair your name with the default mark.
+ </ParamField>
+ </Expandable>
+
+ <Expandable title="BrandLogoConfig">
+ <ParamField path="light" type="string">
+ Source used when the resolved mode is light.
+ </ParamField>
+ <ParamField path="dark" type="string">
+ Source used when the resolved mode is dark.
</ParamField>
- <ParamField path="icon" type="BrandImage">
- Falls back to the bare mark — no name.
+ <ParamField path="src" type="string">
+ Mode-agnostic source, used when neither `light` nor `dark` is set.
</ParamField>
- <ParamField path="name" type="string" default='"TrueFoundry"'>
- Shown beside the default logo.
+ <ParamField path="href" type="string">
+ Wraps the logo in a same-tab link, labelled with `name`.
</ParamField>
</Expandable>
- `BrandImage` accepts `{ src, alt? }`, a React node, or a render function.
+ A single configured mode is used for both modes, so `{ light }` alone never renders a
+ missing image. To render a component rather than an image, override the `BrandLogo` slot
+ through `overrides`.
</ParamField>
<ParamField path="icons" type="IconMap">
Replace registry icons by name. Values are Lucide components, React nodes, render
@@ -194,7 +211,7 @@ Persisted sessions remain available through the thread list.
server={{ type: "truefoundry", apiKey, controlPlaneURL }}
layout="sidebar"
agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "openai-main/gpt-4.1" } } }}
- theme={{ preset: "claude", brand: { name: "Acme" } }}
+ theme={{ preset: "claude", brand: { name: "Acme", logo: "/logo.svg" } }}
overrides={{ ClearChatButton: MyClearButton }}
className="h-full min-h-0"
onError={(e) => reportError(e)}
diff --git a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
index 1c8acc125..82b29c314 100644
--- a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
+++ b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
@@ -67,14 +67,15 @@ A few tokens are absent from the presets — `scrollbarThumb`, `assistantBubble`
## Reading theme state
```tsx
-import { useTheme, useThemeMode, useBrand } from "@truefoundry/trueforge-ui";
+import { useTheme, useThemeMode, useBrand, useBrandName } 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();
+const brandName = useBrandName(); // brand.name, or "TrueForge"
```
-`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.
+`BrandLogo` renders `theme.brand.logo`, resolved against the active mode and labelled with `theme.brand.name`. Omit `logo` — or `brand` entirely — and it falls back to the default mark; `brand` is optional, but setting it requires a `name`. Pair it with `useBrandName()` when you also want the name as text. It is an overridable slot — use `overrides` to render a component instead of an image.
## Token naming
diff --git a/packages/frontend/src/AuthErrorScreen.tsx b/packages/frontend/src/AuthErrorScreen.tsx
index 8ed1f51d9..e559580d0 100644
--- a/packages/frontend/src/AuthErrorScreen.tsx
+++ b/packages/frontend/src/AuthErrorScreen.tsx
@@ -1,4 +1,4 @@
-import { BrandIcon } from '@truefoundry/trueforge-ui';
+import { BrandLogo } from '@truefoundry/trueforge-ui';
import { AUTH_LOGIN_HREF } from './authFetch';
import './authScreens.css';
@@ -8,7 +8,7 @@ export function AuthErrorScreen({ reason }: { reason: string }) {
return (
<main className="auth-screen">
<div className="auth-screen-card">
- <BrandIcon className="auth-screen-logo" />
+ <BrandLogo className="auth-screen-logo" />
<h1 className="auth-screen-title">Sign-in failed</h1>
<p className="auth-screen-message">{message}</p>
<a className="auth-screen-button" href={AUTH_LOGIN_HREF}>
diff --git a/packages/frontend/src/GetStartedScreen.tsx b/packages/frontend/src/GetStartedScreen.tsx
index 3439b585a..b5d4ce10a 100644
--- a/packages/frontend/src/GetStartedScreen.tsx
+++ b/packages/frontend/src/GetStartedScreen.tsx
@@ -1,4 +1,4 @@
-import { BrandIcon } from '@truefoundry/trueforge-ui';
+import { BrandLogo } from '@truefoundry/trueforge-ui';
import { AUTH_LOGIN_HREF } from './authFetch';
import './authScreens.css';
@@ -10,7 +10,7 @@ export function GetStartedScreen() {
return (
<main className="auth-screen">
<div className="auth-screen-card">
- <BrandIcon className="auth-screen-logo" />
+ <BrandLogo className="auth-screen-logo" />
<h1 className="auth-screen-title">Welcome to TrueForge</h1>
<button
type="button"
diff --git a/packages/trueforge-ui-sdk/CHANGELOG.md b/packages/trueforge-ui-sdk/CHANGELOG.md
index 4d02a69e8..eda612b8e 100644
--- a/packages/trueforge-ui-sdk/CHANGELOG.md
+++ b/packages/trueforge-ui-sdk/CHANGELOG.md
@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+
+- **Light/dark brand logo** — `theme.brand.logo` accepts a `BrandLogoConfig`
+ (`{ src?, light?, dark?, href? }`). The source is picked from the resolved theme
+ mode, falling back to the other mode and then `src`, so a single configured mode
+ covers both and `{ light }` alone never renders a missing image. `href` wraps the
+ logo in a same-tab link. A bare string (`logo: '/logo.svg'`) is shorthand for a
+ mode-agnostic source. A config with no usable source falls back to the default
+ mark rather than an empty `<img>`.
+- **`BrandLogo` slot** — now in the slot table and resolved through `useSlot` by
+ every layout, so `overrides={{ BrandLogo: MyMark }}` reaches the sidebar header,
+ widget FAB, and welcome screen.
+- **`useBrandName()`** — the configured brand name or the default, so layouts no
+ longer inline the fallback string.
+
### Changed
- **Styles auto-inject** — `ThemeProvider` injects the SDK stylesheet at runtime.
@@ -40,6 +55,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **`AgentUIServer` / mounts follow the runtime contract** — composed port matches
runtime `AgentUIServerPort`; `SkillMount` / `McpServerMount` stay opaque `object`
(hosts widen via generics). Implement `getCapabilities()` on every builder host.
+- **One brand component** — removed the `BrandIcon` export; `BrandLogo` is the only
+ product mark and renders the mark alone. Callers that also want the name as text
+ pair it with `useBrandName()` (as the sidebar header does), rather than relying on
+ a second component that hard-codes one arrangement. Replace `<BrandIcon />` with
+ `<BrandLogo />`, and `overrides={{ BrandIcon }}` with `overrides={{ BrandLogo }}`.
+- **`brand.name` is required** — `theme.brand` stays optional, but setting it now
+ requires `name`, since it labels the logo and a logo with no name has no accessible
+ name. `logo` remains optional, so `brand: { name: 'Acme' }` still pairs host text
+ with the default mark. `useBrand()` returns `Partial<BrandConfig>`, since `brand`
+ may be absent entirely.
+- **`theme.brand` is images-only** — removed `brand.icon`; there is one logo source.
+ Removed the `ReactNode` and render-function variants of the logo value (and with
+ them the `BrandImage` type export), so `brand.logo` is now
+ `string | BrandLogoConfig`. Component-valued marks move to the slot table:
+ `overrides={{ BrandLogo: MyMark }}`, which is how every other atom is replaced.
+ Also removed `alt` — the logo is labelled with `brand.name`, so there is one place
+ to set the accessible name.
+- **Default brand name is `"TrueForge"`** (was `"TrueFoundry"`), used by
+ `BrandLogo`, the sidebar header, and `useBrandName()`.
- **`ShellMode` shape** — replaced `type: 'idle' | 'named' | 'draft'` with
`status: 'idle' | 'active'` plus `isMutable` on active bindings. Composer /
Save Agent / welcome chrome key off `isMutable`, not draft|named.
diff --git a/packages/trueforge-ui-sdk/README.md b/packages/trueforge-ui-sdk/README.md
index 42de12ebe..7a4e8be39 100644
--- a/packages/trueforge-ui-sdk/README.md
+++ b/packages/trueforge-ui-sdk/README.md
@@ -166,7 +166,7 @@ export default function App() {
}}
theme={{
preset: 'claude',
- brand: { name: 'Acme', icon: { src: '/logo.svg', alt: 'Acme' } },
+ brand: { name: 'Acme', logo: '/logo.svg' },
}}
overrides={{/* slot overrides */}}
className="h-full"
@@ -234,7 +234,7 @@ See [docs/theming.md](./docs/theming.md) for presets, controlled vs uncontrolled
## Brand / logo
-**Base layouts** — pass `theme.brand` and the SDK positions name + icon in the default slots:
+**Base layouts** — pass `theme.brand` and the SDK positions the mark + name in the default slots:
```tsx
<TrueforgeUI
@@ -243,14 +243,38 @@ See [docs/theming.md](./docs/theming.md) for presets, controlled vs uncontrolled
theme={{
brand: {
name: 'Acme',
- icon: { src: '/brand/icon.svg', alt: 'Acme' },
- logo: { src: '/brand/logo.svg', alt: 'Acme' },
+ logo: '/brand/logo.svg',
},
}}
/>
```
-**Custom layouts** — import `BrandLogo` / `BrandIcon` and place them anywhere (see [Custom layouts](#custom-layouts)).
+**Light / dark marks** — pass `light` / `dark` sources instead and the SDK picks the one matching
+the resolved mode. `href` wraps the logo in a same-tab link:
+
+```tsx
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ theme={{
+ brand: {
+ name: 'Acme',
+ logo: { light: '/brand/logo-light.svg', dark: '/brand/logo-dark.svg', href: '/' },
+ },
+ }}
+/>
+```
+
+Set only one mode and it is used for both. `name` labels the image, so no `alt` is needed.
+
+**Component marks** — `theme.brand` takes image URLs only. To render an inline SVG or a custom
+component, override the `BrandLogo` slot, the same way you replace any other atom:
+
+```tsx
+<TrueforgeUI server={server} layout="sidebar" overrides={{ BrandLogo: MyMark }} />
+```
+
+**Custom layouts** — import `BrandLogo` and place it anywhere; pair it with `useBrandName()` when you also want the name as text (see [Custom layouts](#custom-layouts)).
> _Screenshot: external brand mark rendered in the base layout header._
@@ -322,15 +346,17 @@ The [example app](./example/) switches between these four modes.
For full control, pass a React component as `layout`. The SDK still wires server, shell mode, slots, and runtime behind it.
```tsx
-import { Thread, ThreadListContainer, BrandIcon, useTheme } from '@truefoundry/trueforge-ui';
+import { Thread, ThreadListContainer, BrandLogo, useBrandName, useTheme } from '@truefoundry/trueforge-ui';
function Layout({ className }: { className?: string }) {
const { mode, setTheme } = useTheme();
+ const brandName = useBrandName();
return (
<div className={className} style={{ display: 'flex', height: '100%' }}>
<aside style={{ width: 256 }}>
- <BrandIcon className="size-6" />
+ <BrandLogo className="size-6" />
+ <span>{brandName}</span>
<ThreadListContainer />
</aside>
<main style={{ flex: 1, minWidth: 0 }}>
@@ -348,7 +374,7 @@ function Layout({ className }: { className?: string }) {
For deeper composition without `TrueforgeUI`, nest `SlotsProvider` outside `TrueFoundryChatProvider` — see [docs/customization.md](./docs/customization.md).
-> _Screenshot: a custom layout assembled from_ `BrandIcon`_,_ `ThreadListContainer`_, and_ `Thread`_._
+> _Screenshot: a custom layout assembled from_ `BrandLogo`_,_ `ThreadListContainer`_, and_ `Thread`_._
---
@@ -467,7 +493,7 @@ See [docs/server.md](./docs/server.md) for the full method list and BYO guidance
| `TrueforgeUI` | Component | Root component — accepts all props above |
| `TrueforgeServerConfig` | Type | `server` prop: `truefoundry` / `trueforge` / `AgentUIServer` |
| `createTrueFoundryServer` | Function | Compose chat + builder into `AgentUIServer` |
-| `Thread`, `ThreadListContainer`, `BrandLogo`, `BrandIcon` | Components | Layout primitives for custom layouts |
+| `Thread`, `ThreadListContainer`, `BrandLogo` | Components | Layout primitives for custom layouts |
| Composer / message / tool atoms | Components | Overridable, themeable building blocks |
| `SlotsProvider`, `useSlot`, `useTheme` | API | Overrides + theme mode |
| `AgentUIServer`, `AgentChatServer`, `AgentBuilderServer` | Types | Resolved server contract |
diff --git a/packages/trueforge-ui-sdk/docs/customization.md b/packages/trueforge-ui-sdk/docs/customization.md
index af2f8fe58..c91503e10 100644
--- a/packages/trueforge-ui-sdk/docs/customization.md
+++ b/packages/trueforge-ui-sdk/docs/customization.md
@@ -29,7 +29,7 @@ over hacking third-party CSS:
preset: 'claude',
mode: 'dark',
tokens: { primary: '#e11d48' },
- brand: { name: 'Acme', icon: MyMark },
+ brand: { name: 'Acme', logo: '/brand/logo.svg' },
icons: { send: MySendSvg },
classNames: {
markdown: 'prose max-w-none',
diff --git a/packages/trueforge-ui-sdk/docs/server.md b/packages/trueforge-ui-sdk/docs/server.md
index 768cbc9f8..2e7e21318 100644
--- a/packages/trueforge-ui-sdk/docs/server.md
+++ b/packages/trueforge-ui-sdk/docs/server.md
@@ -802,7 +802,6 @@ export function App() {
brand: {
name: 'MyCo',
logo: { src: '/myco-wordmark.svg' },
- icon: { src: '/myco-mark.svg' },
},
}}
/>
diff --git a/packages/trueforge-ui-sdk/docs/theming.md b/packages/trueforge-ui-sdk/docs/theming.md
index 0b11fc3bc..ba0683814 100644
--- a/packages/trueforge-ui-sdk/docs/theming.md
+++ b/packages/trueforge-ui-sdk/docs/theming.md
@@ -16,7 +16,7 @@ the SDK. Layers (each independently overridable):
| ------------------ | -------------------------------------------- | --------------------------------------------- |
| Preset | Baseline look | `theme.preset` |
| Tokens | Colors, radius, fonts, bubble colors | `theme.tokens` + CSS vars |
-| Brand | Logo + brand mark / icon | `theme.brand` |
+| Brand | Logo image + display name | `theme.brand` (marks via slots) |
| Icons | Action / UI icon set | `theme.icons` (Lucide + SVG transforms) |
| Content classNames | Markdown, syntax-highlighter, OpenUI, Monaco | `theme.classNames` |
| Root class | Arbitrary host utilities | `theme.className` |
@@ -41,7 +41,7 @@ track (orthogonal to [`docs/server.md`](./server.md)).
| Coverage | Everything currently pulled from tfy |
| Slot API | **Breaking** — drop `Button.Primary` / icon-string contracts; new shadcn-aligned props |
| Icons | Lucide defaults; host can replace map + supply SVG transforms |
-| Brand | Replacable via `theme.brand` (logo URL/node + brand icon URL/node/SVG) |
+| Brand | Logo URL (per-mode) via `theme.brand`; component marks via the `BrandLogo` slot |
| Theme API | Object (not string-only); every look aspect customizable |
| Presets | Inspired-by packs: `truefoundry` (default), `claude`, `chatgpt`, `gemini` |
| Custom styles | CSS tokens + `className`; host may also import CSS (documented). No “load CSS file” prop |
@@ -84,12 +84,12 @@ props):
### Theme / icons / brand infra
-| Remove | Replace with |
-| -------------------------------- | ------------------------------------------------------------------------------------------- |
-| `tfy-web-components/theme.css` | Own palette + semantic tokens in `styles.css` |
-| tfy `ThemeProvider` / `useTheme` | SDK `ThemeProvider` owned here |
-| `IconProvider` + `registerIcons` | `IconRegistry` + `theme.icons` / `setIcons` |
-| Hard-coded TFY marks | `theme.brand` (logo + brand icon) consumed by header, welcome, widget FAB, avatar fallbacks |
+| Remove | Replace with |
+| -------------------------------- | ---------------------------------------------------------------------------- |
+| `tfy-web-components/theme.css` | Own palette + semantic tokens in `styles.css` |
+| tfy `ThemeProvider` / `useTheme` | SDK `ThemeProvider` owned here |
+| `IconProvider` + `registerIcons` | `IconRegistry` + `theme.icons` / `setIcons` |
+| Hard-coded TFY marks | `theme.brand.logo` consumed by header, welcome, widget FAB, avatar fallbacks |
### Code surfaces (Monaco + syntax highlighter)
@@ -156,30 +156,41 @@ type IconMap = Record<
| React.FC<React.SVGProps<SVGSVGElement>>
>;
-type BrandImage =
- | { src: string; alt?: string }
- | React.ReactNode
- | ((props: { className?: string }) => React.ReactNode);
+/**
+ * Logo sources. `light` / `dark` pick per resolved theme mode and fall back to
+ * each other, then to `src`. `href` wraps the logo in a same-tab link labelled
+ * with the brand name.
+ */
+type BrandLogoConfig = {
+ src?: string;
+ light?: string;
+ dark?: string;
+ href?: string;
+};
/**
* Product branding — distinct from `icons` (UI chrome).
- * Used anywhere a product mark appears today (header, welcome, widget FAB,
+ * Consumed wherever a product mark appears (header, welcome, widget FAB,
* empty states, assistant avatar fallback).
+ *
+ * Images only: to render a component, override the `BrandLogo` slot instead, so
+ * brand marks follow the same replacement path as every other atom.
+ *
+ * `theme.brand` is optional; setting it requires a `name` (it labels the logo).
+ * `logo` is optional — omit it to pair host text with the stock mark.
*/
type BrandConfig = {
- /** Wordmark / wide logo (sidebar header, welcome). */
- logo?: BrandImage;
- /** Square brand mark / app icon (FAB, avatar fallback, compact chrome). */
- icon?: BrandImage;
- /** Optional display name next to logo. */
- name?: string;
+ /** Display name beside the mark, and the logo's accessible label. */
+ name: string;
+ /** Image URL, or per-mode sources. Omit to keep the default mark. */
+ logo?: string | BrandLogoConfig;
};
type ThemeConfig = {
preset?: ThemePreset; // default: "truefoundry"
mode?: ThemeMode; // omit = uncontrolled (useTheme().setTheme)
tokens?: Partial<SemanticTokens>;
- brand?: BrandConfig; // logo + brand icon replacement
+ brand?: BrandConfig; // logo image + display name
className?: string; // applied on .aui-root (or theme root)
icons?: IconMap; // full/partial UI icon replace + SVG transforms
/** Per-surface className hooks for content renderers */
@@ -245,8 +256,7 @@ function MyLayout({ className }: { className?: string }) {
tokens: { primary: '#…', fontFamily: '"My Font", system-ui' },
brand: {
name: 'Acme Agent',
- logo: { src: '/acme-wordmark.svg', alt: 'Acme' },
- icon: MyAcmeMark,
+ logo: { light: '/acme-wordmark.svg', dark: '/acme-wordmark-dark.svg' },
},
className: 'my-chat',
icons: { send: MySendSvg, paperclip: MyAttachSvg },
@@ -299,15 +309,24 @@ as `children`.
## Brand system
-1. All product marks render through `useBrand()` / `<BrandLogo />` /
- `<BrandIcon />` — never hard-coded TFY assets in layouts or atoms.
-2. `BrandLogo` resolves `theme.brand.logo` first. Its default wordmark combines
- the configured name with the resolved `BrandIcon`.
-3. `BrandIcon` resolves `theme.brand.icon`, then `theme.icons.robot`, then the
- registry's Lucide robot fallback.
-4. `theme.brand.name` → accessible labels / text next to logo when provided.
-5. Omitting `brand` keeps the default `TrueFoundry` name and robot mark; hosts
- replace the logo and icon independently.
+1. All product marks render through `<BrandLogo />` — one component, never
+ hard-coded TFY assets in layouts or atoms. Layouts resolve it via `useSlot`, so
+ a host override reaches every call site.
+2. `BrandLogo` renders the mark only. Callers that also want the name as text pair
+ it with `useBrandName()`, so each layout owns its own arrangement (the sidebar
+ sets mark + name; the widget FAB and welcome screen show the mark alone). A
+ second "wordmark" component would only re-encode one caller's arrangement.
+3. `theme.brand` carries **image sources only** (URL or `{ src, light, dark, href }`).
+ Component-valued marks go through the `BrandLogo` slot, so brand replacement
+ uses the same mechanism as every other atom instead of a second node-shaped
+ escape hatch in the theme config.
+4. `theme.brand.name` → the accessible label for a configured logo (and its link,
+ when `href` is set), plus whatever text a caller renders alongside.
+5. Omitting `brand` keeps the default `TrueForge` name and robot mark.
+6. `{ light, dark }` sources resolve against the provider's mode, so a host mark
+ tracks light/dark without a custom component. A single configured mode covers
+ both, so `{ light }` alone never renders a missing image; a config with no
+ usable source falls back to the default mark rather than an empty `<img>`.
## Icon system
@@ -321,7 +340,7 @@ as `children`.
identity stays separate from action icons.
For named UI icons the order is `theme.icons[name]` → registry default. The
-robot is also the final brand fallback, so `theme.brand.icon` still takes
+robot is also the final brand fallback, so `theme.brand.logo` still takes
precedence over `theme.icons.robot`. Preset-specific icons such as
`welcome-sparkle` and OAuth state icons (`oauth-loading`, `oauth-success`,
`oauth-error`) use the same lookup order.
@@ -341,7 +360,7 @@ compose path), for example:
- `Thread` / `ThreadContainer`
- `ThreadListContainer`
- `Composer` pieces / slot-backed atoms as needed
-- Brand helpers (`BrandLogo`, `BrandIcon`) and `useTheme`
+- Brand helpers (`BrandLogo`, `useBrandName`) and `useTheme`
The shell still wraps the custom layout with theme + slots + chat provider;
only the chrome tree is replaced. Equivalent to skipping built-in layouts
@@ -412,7 +431,7 @@ TrueforgeUI({ layout, theme, overrides, … })
├─ merge theme.tokens / brand / icons / classNames / className
├─ layout = built-in | <HostLayout />
└─ defaultSlots → local shadcn primitives + feature atoms
- ├─ BrandLogo / BrandIcon wherever product mark appears
+ ├─ BrandLogo wherever the product mark appears
└─ Markdown / OpenUI / syntax-highlighter / Monaco
(classNames from theme)
```
@@ -434,11 +453,11 @@ TrueforgeUI({ layout, theme, overrides, … })
3. Own `ThemeProvider` / `useTheme` (mode light/dark/system); wire
`SlotsProvider` to it.
4. Apply `theme.className` + CSS vars from `theme.tokens` / `preset` on root.
-5. Introduce `BrandConfig` plumbing (`useBrand`, `<BrandLogo />`,
- `<BrandIcon />`) even if defaults still point at TFY assets.
+5. Introduce `BrandConfig` plumbing (`useBrand`, `useBrandName`,
+ `<BrandLogo />`) even if defaults still point at TFY assets.
**Done when:** app runs with owned tokens (tfy components may still be present);
-host can override `--primary` and swap `theme.brand.icon` / `logo`.
+host can override `--primary` and swap `theme.brand.logo`.
### Phase 2 — shadcn primitives + icon + brand registry
@@ -500,8 +519,8 @@ no longer depends on tfy.
- Prefer
`theme={{ preset, tokens, brand, icons, className, classNames }}`
over hacking a third-party theme.
-- Replace product marks with `theme.brand.logo` / `theme.brand.icon` (URL,
- React node, or SVG component).
+- Replace product marks with `theme.brand.logo` (URL or per-mode sources), or
+ override the `BrandLogo` slot for component marks.
- Pass `layout={MyLayout}` to own chrome; compose `Thread` /
`ThreadListContainer` / etc.
- Style content engines via `theme.classNames` or `.aui-markdown` /
@@ -532,8 +551,8 @@ no longer depends on tfy.
- Host can pass `layout={MyLayout}` built from `Thread` + thread list exports
- Host can override classes on Markdown, syntax-highlighter, OpenUI, and Monaco
via `theme.classNames` and/or stable `aui-*` CSS hooks
-- Host can fully rebrand (colors, fonts, logo, brand icon, action icons)
- without slot overrides
+- Host can fully rebrand (colors, fonts, logo image, action icons) without slot
+ overrides; component-valued marks use the `BrandLogo` slot
- Host can still replace any component via `overrides` when needed
- Light/dark controlled + uncontrolled both work
- Slot override of `Button` works with new API
diff --git a/packages/trueforge-ui-sdk/example/src/App.tsx b/packages/trueforge-ui-sdk/example/src/App.tsx
index 0bf28749d..a18a8b3c6 100644
--- a/packages/trueforge-ui-sdk/example/src/App.tsx
+++ b/packages/trueforge-ui-sdk/example/src/App.tsx
@@ -271,11 +271,10 @@ export default function App() {
theme={{
preset: 'claude',
brand: {
- icon: {
+ logo: {
src: 'https://media.licdn.com/dms/image/v2/C560BAQGQ9Tfeof4MbA/company-logo_200_200/company-logo_200_200/0/1644494262340/truefoundry_logo?e=2147483647&v=beta&t=Xm6c1LGNbVPD2Ehtj21Z5OcuSCGLhYwlJ763oEYb92M',
- alt: 'TrueFoundry',
},
- name: 'TFY',
+ name: 'TrueForge',
},
}}
layout="sidebar"
diff --git a/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx b/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx
index 04dee15ed..dff6a20a5 100644
--- a/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx
+++ b/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx
@@ -1,7 +1,7 @@
import type { ReactNode } from 'react';
import { Icon } from '../icons/Icon.js';
-import { BrandIcon } from '../theme/brand.js';
+import { useSlot } from '../theme/SlotsProvider.js';
import { useOptionalThemePreset } from '../theme/ThemeProvider.js';
import { cn } from './lib/cn.js';
@@ -13,13 +13,14 @@ export type WelcomeScreenProps = {
export function WelcomeScreen({ heading = 'How can I help you today?', icon, className }: WelcomeScreenProps) {
const preset = useOptionalThemePreset();
+ const BrandLogo = useSlot('BrandLogo');
const resolvedIcon =
icon !== undefined ? (
icon
) : preset === 'chatgpt' ? null : preset === 'claude' ? (
<Icon name="welcome-sparkle" className="size-5 fill-current text-primary" />
) : (
- <BrandIcon className={'size-10'} />
+ <BrandLogo className={'size-10'} />
);
return (
diff --git a/packages/trueforge-ui-sdk/src/index.ts b/packages/trueforge-ui-sdk/src/index.ts
index a6ca71920..23fb5a41f 100644
--- a/packages/trueforge-ui-sdk/src/index.ts
+++ b/packages/trueforge-ui-sdk/src/index.ts
@@ -2,7 +2,7 @@
import './icons/registerAgentIcons.js';
-export { BrandIcon, BrandLogo } from './theme/brand.js';
+export { BrandLogo, useBrandName } from './theme/brand.js';
export { defaultSlots } from './theme/defaultSlots.js';
export { PRESETS, resolvePresetTokens } from './theme/presets/index.js';
export type { PublicAtomSlots as AtomSlots, SlotOverrides } from './theme/publicSlots.js';
@@ -17,7 +17,7 @@ export {
} from './theme/ThemeProvider.js';
export type {
BrandConfig,
- BrandImage,
+ BrandLogoConfig,
ContentClassNames,
IconMap,
LayoutProp,
diff --git a/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx
index 26eb31efb..f32b60c6c 100644
--- a/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx
+++ b/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx
@@ -12,9 +12,8 @@ import { Thread } from '../containers/Thread.js';
import { ThreadListContainer } from '../containers/ThreadListContainer.js';
import { Icon } from '../icons/Icon.js';
import { useOptionalShellMode } from '../server/ShellModeContext.js';
-import { BrandIcon } from '../theme/brand.js';
+import { useBrandName } from '../theme/brand.js';
import { useSlot } from '../theme/SlotsProvider.js';
-import { useBrand } from '../theme/ThemeProvider.js';
const TruefoundrySettingsBuilder = lazy(() => import('../containers/SettingsBuilder/index.js'));
@@ -24,7 +23,8 @@ let desktopCollapsed = false;
export function SidebarLayout({ className }: { className?: string }) {
const aui = useAui();
const shell = useOptionalShellMode();
- const brand = useBrand();
+ const brandName = useBrandName();
+ const BrandLogo = useSlot('BrandLogo');
const AgentsLibraryButton = useSlot('AgentsLibraryButton');
const ClearChatButton = useSlot('ClearChatButton');
const SaveAgentButton = useSlot('SaveAgentButton');
@@ -91,10 +91,8 @@ export function SidebarLayout({ className }: { className?: string }) {
className={cn('flex shrink-0 items-center px-3 py-3', collapsed ? 'flex-col gap-3' : 'justify-between gap-2')}
>
<div className={cn('flex min-w-0 items-center text-foreground', collapsed ? 'justify-center' : 'gap-2')}>
- <BrandIcon className="size-6 shrink-0 object-contain" />
- {!collapsed ? (
- <span className="truncate text-lg font-semibold tracking-tight">{brand.name ?? 'TrueFoundry'}</span>
- ) : null}
+ <BrandLogo className="size-6 shrink-0 object-contain" />
+ {!collapsed ? <span className="truncate text-lg font-semibold tracking-tight">{brandName}</span> : null}
</div>
<button
type="button"
@@ -214,8 +212,8 @@ export function SidebarLayout({ className }: { className?: string }) {
tabIndex={-1}
>
<div className="flex shrink-0 items-center gap-2 border-b border-border px-3 py-3 text-foreground">
- <BrandIcon className="size-6 shrink-0 object-contain" />
- <span className="truncate text-lg font-semibold tracking-tight">{brand.name ?? 'TrueFoundry'}</span>
+ <BrandLogo className="size-6 shrink-0 object-contain" />
+ <span className="truncate text-lg font-semibold tracking-tight">{brandName}</span>
</div>
<ThreadListContainer onThreadOpen={() => setMobileNavOpen(false)} />
</div>
diff --git a/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx
index 97e004888..5ae19d32d 100644
--- a/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx
+++ b/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx
@@ -6,11 +6,12 @@ import { auiButtonClass } from '../atoms/lib/buttonClasses.js';
import { cn } from '../atoms/lib/cn.js';
import { CompactLayoutProvider } from '../atoms/lib/CompactLayoutContext.js';
import { Icon } from '../icons/Icon.js';
-import { BrandIcon } from '../theme/brand.js';
+import { useSlot } from '../theme/SlotsProvider.js';
import { StackChatPanel } from './StackChatPanel.js';
/** FAB-anchored panel with the same list ↔ thread stack as `dock`. */
export function WidgetLayout({ className }: { className?: string }) {
+ const BrandLogo = useSlot('BrandLogo');
const [open, setOpen] = useState(false);
const fabRef = useRef<HTMLButtonElement>(null);
const dialogRef = useRef<HTMLDivElement>(null);
@@ -86,7 +87,7 @@ export function WidgetLayout({ className }: { className?: string }) {
×
</span>
) : (
- <BrandIcon className="size-6" />
+ <BrandLogo className="size-6" />
)}
</button>
</div>
diff --git a/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx b/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx
index 758817c52..2e8e60bfd 100644
--- a/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx
+++ b/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx
@@ -34,7 +34,8 @@ export type ThemeContextValue = {
preference: ThemeMode;
isDark: boolean;
setTheme: (mode: ThemeMode) => void;
- brand: BrandConfig;
+ /** Partial: `theme.brand` is optional, so consumers fall back to SDK defaults. */
+ brand: Partial<BrandConfig>;
icons: IconMap;
classNames: ContentClassNames;
tokens: Partial<SemanticTokens>;
@@ -174,7 +175,8 @@ export function useTheme(): Pick<ThemeContextValue, 'preset' | 'mode' | 'prefere
return { preset, mode, preference, isDark, setTheme };
}
-export function useBrand(): BrandConfig {
+/** Configured branding. Fields are optional — `theme.brand` may be omitted entirely. */
+export function useBrand(): Partial<BrandConfig> {
return useThemeContext().brand;
}
diff --git a/packages/trueforge-ui-sdk/src/theme/brand.tsx b/packages/trueforge-ui-sdk/src/theme/brand.tsx
index 35f144a08..9fc815550 100644
--- a/packages/trueforge-ui-sdk/src/theme/brand.tsx
+++ b/packages/trueforge-ui-sdk/src/theme/brand.tsx
@@ -1,47 +1,61 @@
'use client';
-import type { ReactNode } from 'react';
-
import { useContext } from 'react';
-import { cn } from '../atoms/lib/cn.js';
import { Icon } from '../icons/Icon.js';
import { ThemeContext } from './ThemeProvider.js';
-import type { BrandConfig, BrandImage } from './types.js';
-
-function DefaultBrandIcon({ className }: { className?: string }) {
- return <Icon name="robot" className={className} />;
+import type { BrandLogoConfig } from './types.js';
+
+const DEFAULT_BRAND_NAME = 'TrueForge';
+
+/** Mode-matched source, falling back to the other mode then the mode-agnostic `src`. */
+function resolveLogoSrc({
+ logo,
+ mode,
+}: {
+ logo: string | BrandLogoConfig;
+ mode: 'light' | 'dark';
+}): string | undefined {
+ if (typeof logo === 'string') return logo;
+ const preferred = mode === 'dark' ? logo.dark : logo.light;
+ return preferred ?? logo.light ?? logo.dark ?? logo.src;
}
-function DefaultBrandLogo({ className, name }: { className?: string; name: string }) {
- return (
- <span className={cn('inline-flex items-center gap-2 font-semibold tracking-tight', className)}>
- <BrandIcon className="size-5" />
- <span>{name}</span>
- </span>
- );
+/** Configured brand name, or the SDK default. Safe outside a `ThemeProvider`. */
+export function useBrandName(): string {
+ return useContext(ThemeContext)?.brand.name ?? DEFAULT_BRAND_NAME;
}
-function renderBrandImage(image: BrandImage | undefined, fallback: ReactNode, className?: string): ReactNode {
- if (image == null) return fallback;
- if (typeof image === 'function') return image({ className });
- if (typeof image === 'object' && image !== null && 'src' in image) {
- return <img src={image.src} alt={image.alt ?? ''} className={className} />;
- }
- return image;
-}
+/**
+ * The product mark: `theme.brand.logo` resolved against the active theme mode,
+ * labelled with the brand name, and linked when the config carries an `href`.
+ * Falls back to the default mark when no logo is configured.
+ *
+ * Callers that also want the name as text render it themselves — the SDK layouts
+ * pair this with `useBrandName()` so each one controls its own arrangement.
+ */
+export function BrandLogo({ className }: { className?: string }) {
+ const theme = useContext(ThemeContext);
+ const logo = theme?.brand.logo;
+ const name = theme?.brand.name ?? DEFAULT_BRAND_NAME;
-function useOptionalBrand(): BrandConfig {
- return useContext(ThemeContext)?.brand ?? {};
-}
+ const src = logo == null ? undefined : resolveLogoSrc({ logo, mode: theme?.mode ?? 'light' });
+ if (src == null) return <Icon name="robot" className={className} />;
-export function BrandLogo({ className }: { className?: string }) {
- const brand = useOptionalBrand();
- const name = brand.name ?? 'TrueFoundry';
- return <>{renderBrandImage(brand.logo, <DefaultBrandLogo className={className} name={name} />, className)}</>;
+ // `name` is the accessible label: the image itself carries no text alternative.
+ const image = <img src={src} alt={name} className={className} />;
+ const href = typeof logo === 'string' ? undefined : logo?.href;
+ if (href == null) return image;
+
+ return (
+ <a href={href} aria-label={name} className="inline-flex items-center">
+ {image}
+ </a>
+ );
}
-export function BrandIcon({ className }: { className?: string }) {
- const brand = useOptionalBrand();
- return <>{renderBrandImage(brand.icon, <DefaultBrandIcon className={className} />, className)}</>;
+declare module './SlotsProvider.js' {
+ interface AtomSlots {
+ BrandLogo: typeof BrandLogo;
+ }
}
diff --git a/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts b/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts
index f2071d4f5..0e212fbfd 100644
--- a/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts
+++ b/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts
@@ -53,6 +53,7 @@ import { UserMessageActionBar } from '../atoms/UserMessageActionBar.js';
import { UserMessageBubble } from '../atoms/UserMessageBubble.js';
import { UserMessageEdit } from '../atoms/UserMessageEdit.js';
import { WelcomeScreen } from '../atoms/WelcomeScreen.js';
+import { BrandLogo } from './brand.js';
import type { AtomSlots } from './SlotsProvider.js';
// ponytail: primitives stay CSS/token-styled (not slots) — see docs/customization.md.
@@ -68,6 +69,7 @@ export const defaultSlots = {
Accordion,
AccordionSummary,
AccordionDetails,
+ BrandLogo,
ComposerShell,
ComposerLeftSection,
ComposerRightSection,
diff --git a/packages/trueforge-ui-sdk/src/theme/types.ts b/packages/trueforge-ui-sdk/src/theme/types.ts
index e64f6a723..cfd4339f7 100644
--- a/packages/trueforge-ui-sdk/src/theme/types.ts
+++ b/packages/trueforge-ui-sdk/src/theme/types.ts
@@ -55,12 +55,29 @@ export type IconEntry = IconComponent | ReactNode;
export type IconMap = Record<string, IconEntry>;
-export type BrandImage = { src: string; alt?: string } | ReactNode | ((props: { className?: string }) => ReactNode);
+/**
+ * Logo sources. `light` / `dark` pick per resolved theme mode and fall back to
+ * each other, then to `src`. `href` wraps the logo in a same-tab link. The logo
+ * is labelled with `name`; replace the mark itself through the slot table when
+ * an image URL is not enough.
+ */
+export type BrandLogoConfig = {
+ src?: string;
+ light?: string;
+ dark?: string;
+ href?: string;
+};
+/**
+ * Setting `brand` requires a `name`: it labels the logo, so a logo without one has
+ * no accessible name. `logo` is optional — omit it to pair host text with the stock
+ * mark.
+ */
export type BrandConfig = {
- logo?: BrandImage;
- icon?: BrandImage;
- name?: string;
+ /** Display name, and the logo's accessible label. */
+ name: string;
+ /** Image URL, or per-mode sources. Omit to keep the default mark. */
+ logo?: string | BrandLogoConfig;
};
export type ContentClassNames = {
diff --git a/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx b/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx
index ef9d1feea..98358063b 100644
--- a/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx
+++ b/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx
@@ -243,7 +243,7 @@ describe('StackChatPanel', () => {
describe('SidebarLayout', () => {
it('shows the app brand in the mobile sessions drawer', () => {
render(
- <SlotsProvider theme={{ brand: { name: 'Acme', icon: { src: '/acme.svg', alt: 'Acme logo' } } }}>
+ <SlotsProvider theme={{ brand: { name: 'Acme', logo: { src: '/acme.svg' } } }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
@@ -256,12 +256,12 @@ describe('SidebarLayout', () => {
const drawer = screen.getByRole('dialog', { name: 'Sessions' });
expect(within(drawer).getByText('Acme')).toBeInTheDocument();
- expect(within(drawer).getByAltText('Acme logo')).toBeInTheDocument();
+ expect(within(drawer).getByAltText('Acme')).toHaveAttribute('src', '/acme.svg');
});
it('shows the brand and toggles the desktop sidebar rail', () => {
const { unmount } = render(
- <SlotsProvider theme={{ brand: { name: 'Acme' } }}>
+ <SlotsProvider theme={{ brand: { name: 'Acme', logo: '/acme.svg' } }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
@@ -280,7 +280,7 @@ describe('SidebarLayout', () => {
// New Chat / Agents remount ChatProvider via runtimeKey; collapse must survive.
unmount();
render(
- <SlotsProvider theme={{ brand: { name: 'Acme' } }}>
+ <SlotsProvider theme={{ brand: { name: 'Acme', logo: '/acme.svg' } }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
diff --git a/packages/trueforge-ui-sdk/test/publicUiExports.test.ts b/packages/trueforge-ui-sdk/test/publicUiExports.test.ts
index f226003c7..51b6c67bd 100644
--- a/packages/trueforge-ui-sdk/test/publicUiExports.test.ts
+++ b/packages/trueforge-ui-sdk/test/publicUiExports.test.ts
@@ -18,7 +18,6 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'AvatarFallback',
'AvatarImage',
'BottomSheet',
- 'BrandIcon',
'BrandLogo',
'CenteredModal',
'ChatFileDownload',
@@ -113,6 +112,7 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'useAui',
'useAuiState',
'useBrand',
+ 'useBrandName',
'useCatalogServer',
'useComposerBusyState',
'useComposerPauseView',
diff --git a/packages/trueforge-ui-sdk/test/theme/ThemeProvider.test.tsx b/packages/trueforge-ui-sdk/test/theme/ThemeProvider.test.tsx
index 067d5e16e..dad4f5f9d 100644
--- a/packages/trueforge-ui-sdk/test/theme/ThemeProvider.test.tsx
+++ b/packages/trueforge-ui-sdk/test/theme/ThemeProvider.test.tsx
@@ -3,7 +3,7 @@ import { act, render, renderHook, screen } from '@testing-library/react';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { WelcomeScreen } from '@/atoms/WelcomeScreen.js';
-import { BrandIcon, BrandLogo } from '@/theme/brand.js';
+import { BrandLogo } from '@/theme/brand.js';
import { ThemeProvider, useBrand, useTheme } from '@/theme/ThemeProvider.js';
function ModeProbe() {
@@ -136,16 +136,15 @@ describe('ThemeProvider', () => {
expect(removeEventListener).toHaveBeenCalledWith('change', expect.any(Function));
});
- it('exposes brand config and BrandLogo / BrandIcon', () => {
+ it('exposes brand config and labels BrandLogo with the brand name', () => {
render(
- <ThemeProvider theme={{ brand: { name: 'Acme' } }}>
+ <ThemeProvider theme={{ brand: { name: 'Acme', logo: '/acme.svg' } }}>
<BrandProbe />
- <BrandLogo />
- <BrandIcon className="size-4" />
+ <BrandLogo className="size-4" />
</ThemeProvider>,
);
expect(screen.getByTestId('brand-name')).toHaveTextContent('Acme');
- expect(screen.getAllByText('Acme').length).toBeGreaterThanOrEqual(1);
+ expect(screen.getByRole('img', { name: 'Acme' })).toHaveAttribute('src', '/acme.svg');
});
it('writes token CSS vars on the theme root', () => {
diff --git a/packages/trueforge-ui-sdk/test/theme/brand.test.tsx b/packages/trueforge-ui-sdk/test/theme/brand.test.tsx
index 48f7c795c..cf9404835 100644
--- a/packages/trueforge-ui-sdk/test/theme/brand.test.tsx
+++ b/packages/trueforge-ui-sdk/test/theme/brand.test.tsx
@@ -1,61 +1,140 @@
import { render, screen } from '@testing-library/react';
import { describe, expect, it } from 'vitest';
-import { BrandIcon, BrandLogo } from '@/theme/brand.js';
+import { WelcomeScreen } from '@/atoms/WelcomeScreen.js';
+import { BrandLogo, useBrandName } from '@/theme/brand.js';
+import { SlotsProvider } from '@/theme/SlotsProvider.js';
import { ThemeProvider } from '@/theme/ThemeProvider.js';
-describe('BrandIcon and BrandLogo', () => {
- it('renders accessible default branding without a provider', () => {
+function BrandNameProbe() {
+ return <output data-testid="brand-name">{useBrandName()}</output>;
+}
+
+describe('BrandLogo', () => {
+ it('renders the default mark without a provider', () => {
+ const { container } = render(<BrandLogo className="host-logo" />);
+
+ const icon = container.querySelector('svg[aria-hidden="true"]');
+ expect(icon).toHaveClass('host-logo');
+ });
+
+ it('labels the configured logo with the brand name', () => {
+ render(
+ <ThemeProvider theme={{ brand: { name: 'Acme', logo: { src: '/acme-logo.svg' } } }}>
+ <BrandLogo className="logo-image" />
+ </ThemeProvider>,
+ );
+
+ const logo = screen.getByRole('img', { name: 'Acme' });
+ expect(logo).toHaveAttribute('src', '/acme-logo.svg');
+ expect(logo).toHaveClass('logo-image');
+ });
+
+ it('renders the default mark and name when brand is omitted', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'claude' }}>
+ <BrandNameProbe />
+ <BrandLogo className="host-logo" />
+ </ThemeProvider>,
+ );
+
+ expect(container.querySelector('img')).toBeNull();
+ expect(container.querySelector('svg[aria-hidden="true"]')).toHaveClass('host-logo');
+ expect(screen.getByTestId('brand-name')).toHaveTextContent('TrueForge');
+ });
+
+ it('pairs a host name with the default mark when logo is omitted', () => {
const { container } = render(
- <>
+ <ThemeProvider theme={{ brand: { name: 'Acme' } }}>
+ <BrandNameProbe />
<BrandLogo className="host-logo" />
- <BrandIcon className="host-icon" />
- </>,
+ </ThemeProvider>,
);
- expect(screen.getByText('TrueFoundry').parentElement).toHaveClass('host-logo');
- const icons = container.querySelectorAll('svg[aria-hidden="true"]');
- expect(icons).toHaveLength(2);
- expect(icons[1]).toHaveClass('host-icon');
+ expect(container.querySelector('img')).toBeNull();
+ expect(container.querySelector('svg[aria-hidden="true"]')).toHaveClass('host-logo');
+ expect(screen.getByTestId('brand-name')).toHaveTextContent('Acme');
});
- it('renders configured image descriptors with alt text and classes', () => {
+ it('treats a bare string as an image source', () => {
render(
- <ThemeProvider
- theme={{
- brand: {
- logo: { src: '/acme-logo.svg', alt: 'Acme logo' },
- icon: { src: '/acme-icon.svg', alt: 'Acme icon' },
- },
- }}
- >
+ <ThemeProvider theme={{ brand: { logo: '/acme-logo.svg', name: 'Acme' } }}>
<BrandLogo className="logo-image" />
- <BrandIcon className="icon-image" />
</ThemeProvider>,
);
- expect(screen.getByRole('img', { name: 'Acme logo' })).toHaveAttribute('src', '/acme-logo.svg');
- expect(screen.getByRole('img', { name: 'Acme logo' })).toHaveClass('logo-image');
- expect(screen.getByRole('img', { name: 'Acme icon' })).toHaveAttribute('src', '/acme-icon.svg');
- expect(screen.getByRole('img', { name: 'Acme icon' })).toHaveClass('icon-image');
+ const img = screen.getByRole('img', { name: 'Acme' });
+ expect(img).toHaveAttribute('src', '/acme-logo.svg');
+ expect(img).toHaveClass('logo-image');
+ });
+
+ it('picks the light source in light mode and the dark source in dark mode', () => {
+ const logo = { light: '/logo/light.svg', dark: '/logo/dark.svg' };
+
+ const { rerender } = render(
+ <ThemeProvider theme={{ mode: 'light', brand: { name: 'Acme', logo } }}>
+ <BrandLogo />
+ </ThemeProvider>,
+ );
+ expect(screen.getByRole('img', { name: 'Acme' })).toHaveAttribute('src', '/logo/light.svg');
+
+ rerender(
+ <ThemeProvider theme={{ mode: 'dark', brand: { name: 'Acme', logo } }}>
+ <BrandLogo />
+ </ThemeProvider>,
+ );
+ expect(screen.getByRole('img', { name: 'Acme' })).toHaveAttribute('src', '/logo/dark.svg');
+ });
+
+ it('falls back to the other mode when only one source is configured', () => {
+ render(
+ <ThemeProvider theme={{ mode: 'dark', brand: { name: 'Acme', logo: { light: '/logo/light.svg' } } }}>
+ <BrandLogo />
+ </ThemeProvider>,
+ );
+
+ expect(screen.getByRole('img', { name: 'Acme' })).toHaveAttribute('src', '/logo/light.svg');
});
- it('supports render callbacks and passes through the requested class', () => {
+ it('wraps the logo in a same-tab link when href is set', () => {
render(
<ThemeProvider
- theme={{
- brand: {
- logo: ({ className }) => <span className={className}>Callback logo</span>,
- icon: ({ className }) => <span className={className}>Callback icon</span>,
- },
- }}
+ theme={{ brand: { name: 'Acme', logo: { light: '/logo/light.svg', href: 'https://trueforge.dev' } } }}
>
- <BrandLogo className="custom-logo" />
- <BrandIcon className="custom-icon" />
+ <BrandLogo />
+ </ThemeProvider>,
+ );
+
+ const link = screen.getByRole('link', { name: 'Acme' });
+ expect(link).toHaveAttribute('href', 'https://trueforge.dev');
+ expect(link).not.toHaveAttribute('target');
+ expect(link.querySelector('img')).toHaveAttribute('src', '/logo/light.svg');
+ });
+
+ it('lets a slot override replace the mark with a component', () => {
+ function CustomMark({ className }: { className?: string }) {
+ return <span className={className}>custom mark</span>;
+ }
+
+ render(
+ <SlotsProvider overrides={{ BrandLogo: CustomMark }} theme={{ brand: { name: 'Acme', logo: '/logo.svg' } }}>
+ <WelcomeScreen />
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByText('custom mark')).toBeInTheDocument();
+ expect(screen.queryByRole('img', { name: 'Acme' })).toBeNull();
+ });
+
+ it('falls back to the default mark when a logo config resolves to no source', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ brand: { name: 'Acme', logo: { href: '/' } } }}>
+ <BrandLogo className="host-logo" />
</ThemeProvider>,
);
- expect(screen.getByText('Callback logo')).toHaveClass('custom-logo');
- expect(screen.getByText('Callback icon')).toHaveClass('custom-icon');
+ expect(container.querySelector('img')).toBeNull();
+ expect(container.querySelector('a')).toBeNull();
+ expect(container.querySelector('svg[aria-hidden="true"]')).toHaveClass('host-logo');
});
});