From ae696478b4dc1eecddf98fd49b5eef1c58a948e4 Mon Sep 17 00:00:00 2001
From: Daniel Kantor <kd@stacklok.com>
Date: Fri, 15 May 2026 19:35:15 +0200
Subject: [PATCH 1/6] feat: add color scheme customization

---
 branding-examples/README.md                   |  24 +++
 branding-examples/test-theme.json             |  87 +++++++++++
 .../branding/__tests__/color-tokens.test.ts   |  98 ++++++++++++
 common/branding/color-tokens.ts               | 120 +++++++++++++++
 common/branding/schema.ts                     |  35 +++++
 main/src/branding/__tests__/load.test.ts      | 144 ++++++++++++++++++
 main/src/branding/load.ts                     |  73 +++++++++
 main/src/branding/paths.ts                    |  23 +++
 main/src/main-window.ts                       |  10 ++
 package.json                                  |   1 +
 preload/src/api/__tests__/branding.test.ts    |  53 +++++++
 preload/src/api/branding.ts                   |  39 +++++
 preload/src/preload.ts                        |   5 +-
 renderer/src/common/mocks/electronAPI.ts      |   1 +
 renderer/src/index.css                        |  19 +++
 renderer/src/renderer.tsx                     |  14 ++
 scripts/start-custom-theme.ts                 |  38 +++++
 vitest.setup.ts                               |   1 +
 18 files changed, 784 insertions(+), 1 deletion(-)
 create mode 100644 branding-examples/README.md
 create mode 100644 branding-examples/test-theme.json
 create mode 100644 common/branding/__tests__/color-tokens.test.ts
 create mode 100644 common/branding/color-tokens.ts
 create mode 100644 common/branding/schema.ts
 create mode 100644 main/src/branding/__tests__/load.test.ts
 create mode 100644 main/src/branding/load.ts
 create mode 100644 main/src/branding/paths.ts
 create mode 100644 preload/src/api/__tests__/branding.test.ts
 create mode 100644 preload/src/api/branding.ts
 create mode 100644 scripts/start-custom-theme.ts

diff --git a/branding-examples/README.md b/branding-examples/README.md
new file mode 100644
index 000000000..a690fd671
--- /dev/null
+++ b/branding-examples/README.md
@@ -0,0 +1,24 @@
+# Branding examples
+
+JSON files matching the `BrandingConfig` schema (`common/branding/schema.ts`). Point `BRANDING_CONFIG_PATH` at one and launch — they replace the default Stacklok palette without touching code.
+
+- `test-theme.json` — wine / coral / gold palette, deliberately distinct from studio's defaults. Used by `pnpm run start:customTheme` to stress-test that every themeable surface is wired to the override.
+
+To use any of these on a normal launch, copy to `<userData>/branding-0.json`:
+
+```bash
+# Linux
+cp branding-examples/test-theme.json ~/.config/ToolHive/branding-0.json
+# macOS
+cp branding-examples/test-theme.json "$HOME/Library/Application Support/ToolHive/branding-0.json"
+```
+
+Or override the path entirely:
+
+```bash
+BRANDING_CONFIG_PATH="$PWD/branding-examples/test-theme.json" pnpm run start
+```
+
+## Schema
+
+See `common/branding/schema.ts`. Values must be complete CSS colors (`#hex`, `hsl(...)`, `oklch(...)`, `oklab(...)`, `rgb(...)`, `lab(...)`, `lch(...)`, `color(...)`, or CSS named colors). Bare HSL triplets like `0 60% 20%` are **not** supported — studio consumes vars as bare `var(--X)`, which needs a complete `<color>` value.
diff --git a/branding-examples/test-theme.json b/branding-examples/test-theme.json
new file mode 100644
index 000000000..e3594e632
--- /dev/null
+++ b/branding-examples/test-theme.json
@@ -0,0 +1,87 @@
+{
+  "app_name": "ToolHive (test-theme)",
+  "design_tokens": {
+    "colors": {
+      "light": {
+        "background": "oklch(0.98 0.005 30)",
+        "foreground": "oklch(0.18 0.04 350)",
+        "card": "oklch(0.99 0.008 30)",
+        "card-foreground": "oklch(0.18 0.04 350)",
+        "popover": "oklch(0.99 0.008 30)",
+        "popover-foreground": "oklch(0.18 0.04 350)",
+        "primary": "oklch(0.40 0.20 15)",
+        "primary-foreground": "oklch(0.98 0.005 30)",
+        "secondary": "oklch(0.94 0.03 30)",
+        "secondary-foreground": "oklch(0.28 0.10 15)",
+        "muted": "oklch(0.93 0.02 30)",
+        "muted-foreground": "oklch(0.50 0.05 30)",
+        "accent": "oklch(0.86 0.13 55)",
+        "accent-foreground": "oklch(0.25 0.10 15)",
+        "destructive": "oklch(0.55 0.25 25)",
+        "destructive-foreground": "oklch(0.98 0.005 30)",
+        "border": "oklch(0.88 0.04 25)",
+        "input": "oklch(0.88 0.04 25)",
+        "ring": "oklch(0.50 0.20 15)",
+        "avatar-background": "oklch(0.70 0.10 30 / 89.8%)",
+        "nav-background": "oklch(0.30 0.15 10)",
+        "nav-border": "oklch(0.38 0.16 10)",
+        "nav-button-active-bg": "oklch(0.50 0.22 20)",
+        "nav-button-active-text": "oklch(0.98 0.005 30)",
+        "nav-foreground": "oklch(0.98 0.005 30)",
+        "success": "oklch(0.55 0.15 145)",
+        "warning": "oklch(0.78 0.17 75)",
+        "warning-foreground": "oklch(0.22 0.08 75)",
+        "info": "oklch(0.60 0.18 35)",
+        "info-foreground": "oklch(0.98 0.005 30)",
+        "sidebar": "oklch(0.96 0.02 30)",
+        "sidebar-foreground": "oklch(0.25 0.06 15)",
+        "sidebar-primary": "oklch(0.40 0.20 15)",
+        "sidebar-primary-foreground": "oklch(0.98 0.005 30)",
+        "sidebar-accent": "oklch(0.92 0.05 30)",
+        "sidebar-accent-foreground": "oklch(0.30 0.10 15)",
+        "sidebar-border": "oklch(0.86 0.04 25)",
+        "sidebar-ring": "oklch(0.55 0.20 15)"
+      },
+      "dark": {
+        "background": "oklch(0.16 0.05 350)",
+        "foreground": "oklch(0.96 0.02 30)",
+        "card": "oklch(0.20 0.06 350)",
+        "card-foreground": "oklch(0.96 0.02 30)",
+        "popover": "oklch(0.20 0.06 350)",
+        "popover-foreground": "oklch(0.96 0.02 30)",
+        "primary": "oklch(0.75 0.16 25)",
+        "primary-foreground": "oklch(0.16 0.05 350)",
+        "secondary": "oklch(0.26 0.07 350)",
+        "secondary-foreground": "oklch(0.96 0.02 30)",
+        "muted": "oklch(0.26 0.07 350)",
+        "muted-foreground": "oklch(0.72 0.05 30)",
+        "accent": "oklch(0.42 0.16 25)",
+        "accent-foreground": "oklch(0.96 0.02 30)",
+        "destructive": "oklch(0.55 0.25 25)",
+        "destructive-foreground": "oklch(0.96 0.02 30)",
+        "border": "oklch(0.30 0.07 350)",
+        "input": "oklch(0.30 0.07 350)",
+        "ring": "oklch(0.70 0.18 25)",
+        "avatar-background": "oklch(0.50 0.10 30 / 89.8%)",
+        "nav-background": "oklch(0.10 0.05 350)",
+        "nav-border": "oklch(0.22 0.07 350)",
+        "nav-button-active-bg": "oklch(0.50 0.22 20)",
+        "nav-button-active-text": "oklch(0.98 0.005 30)",
+        "nav-foreground": "oklch(0.98 0.005 30)",
+        "success": "oklch(0.65 0.15 145)",
+        "warning": "oklch(0.80 0.16 75)",
+        "warning-foreground": "oklch(0.22 0.08 75)",
+        "info": "oklch(0.70 0.16 35)",
+        "info-foreground": "oklch(0.16 0.05 350)",
+        "sidebar": "oklch(0.13 0.05 350)",
+        "sidebar-foreground": "oklch(0.94 0.03 30)",
+        "sidebar-primary": "oklch(0.75 0.16 25)",
+        "sidebar-primary-foreground": "oklch(0.16 0.05 350)",
+        "sidebar-accent": "oklch(0.26 0.07 350)",
+        "sidebar-accent-foreground": "oklch(0.94 0.03 30)",
+        "sidebar-border": "oklch(0.26 0.07 350)",
+        "sidebar-ring": "oklch(0.70 0.18 25)"
+      }
+    }
+  }
+}
diff --git a/common/branding/__tests__/color-tokens.test.ts b/common/branding/__tests__/color-tokens.test.ts
new file mode 100644
index 000000000..774fbedd2
--- /dev/null
+++ b/common/branding/__tests__/color-tokens.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest'
+import {
+  colorTokensToStyleContent,
+  tokensToCssDeclarations,
+} from '@common/branding/color-tokens'
+
+describe('tokensToCssDeclarations', () => {
+  it('returns an empty string for undefined', () => {
+    expect(tokensToCssDeclarations(undefined)).toBe('')
+  })
+
+  it('returns an empty string for an empty object', () => {
+    expect(tokensToCssDeclarations({})).toBe('')
+  })
+
+  it('emits a known key with a valid value', () => {
+    expect(tokensToCssDeclarations({ primary: '#ff6600' })).toBe(
+      '--primary: #ff6600;'
+    )
+  })
+
+  it('joins multiple keys with single spaces', () => {
+    const out = tokensToCssDeclarations({
+      primary: '#ff6600',
+      secondary: '#0066ff',
+    })
+    expect(out).toBe('--primary: #ff6600; --secondary: #0066ff;')
+  })
+
+  it('drops unknown keys silently', () => {
+    // ColorTokens permits any string key on the wire; the runtime allowlist
+    // filters non-token keys before they're emitted as CSS variables.
+    const out = tokensToCssDeclarations({
+      'not-a-real-key': '#000',
+      primary: '#fff',
+    })
+    expect(out).toBe('--primary: #fff;')
+  })
+
+  it.each([
+    ['semicolon-injection', '#fff; background: url(x)'],
+    ['closing-brace', '#fff }'],
+    ['opening-comment', '/* nope'],
+    ['closing-comment', '*/'],
+    ['newline', '#fff\n--evil: 1'],
+    ['empty-string', ''],
+    ['over-length', 'a'.repeat(101)],
+  ])('drops values rejected by the safety check (%s)', (_label, badValue) => {
+    expect(tokensToCssDeclarations({ primary: badValue })).toBe('')
+  })
+
+  it('accepts oklch and hsl values', () => {
+    const out = tokensToCssDeclarations({
+      'nav-background': 'oklch(0.4282 0.0561 216.14)',
+      sidebar: 'hsl(40 20% 98.5%)',
+    })
+    expect(out).toContain('--nav-background: oklch(0.4282 0.0561 216.14);')
+    expect(out).toContain('--sidebar: hsl(40 20% 98.5%);')
+  })
+})
+
+describe('colorTokensToStyleContent', () => {
+  it('returns an empty string when theme is null', () => {
+    expect(colorTokensToStyleContent(null)).toBe('')
+  })
+
+  it('returns an empty string when theme is empty', () => {
+    expect(colorTokensToStyleContent({})).toBe('')
+  })
+
+  it('emits a :root:not(.dark) block for light overrides', () => {
+    const out = colorTokensToStyleContent({ light: { primary: '#fff' } })
+    expect(out).toBe(':root:not(.dark) { --primary: #fff; }')
+  })
+
+  it('emits a .dark block for dark overrides', () => {
+    const out = colorTokensToStyleContent({ dark: { primary: '#000' } })
+    expect(out).toBe('.dark { --primary: #000; }')
+  })
+
+  it('emits both blocks when both modes are set', () => {
+    const out = colorTokensToStyleContent({
+      light: { primary: '#fff' },
+      dark: { primary: '#000' },
+    })
+    expect(out).toBe(
+      ':root:not(.dark) { --primary: #fff; } .dark { --primary: #000; }'
+    )
+  })
+
+  it('returns an empty string when every supplied value is invalid', () => {
+    expect(
+      colorTokensToStyleContent({
+        light: { primary: 'color: red; }' },
+      })
+    ).toBe('')
+  })
+})
diff --git a/common/branding/color-tokens.ts b/common/branding/color-tokens.ts
new file mode 100644
index 000000000..4164c4240
--- /dev/null
+++ b/common/branding/color-tokens.ts
@@ -0,0 +1,120 @@
+// SEP#725 — brand color customization. Port of cloud-ui's `color-tokens.ts`
+// (see `sep/enterprise/toolhive-cloud-ui/src/lib/color-tokens.ts`).
+//
+// Override values are emitted into a `<style>` tag at runtime, so they reach
+// the browser as raw CSS. Values MUST be sanitized before emission to prevent
+// stylesheet escape via `;`, `}`, comment markers, etc.
+
+// Per-mode color overrides from `BrandingConfig.design_tokens.colors`.
+export type ColorTokens = {
+  light?: { [key: string]: string }
+  dark?: { [key: string]: string }
+}
+
+// Allowlist of CSS variable names that may be overridden. Mirrors cloud-ui's
+// list so a single `BrandingConfig` JSON is portable across both surfaces.
+// Studio's `renderer/src/index.css` declares all of these except
+// `avatar-background` and `destructive-foreground`; those two are silently
+// no-ops here until studio's CSS adds them, but stay in the allowlist so
+// configs authored for cloud-ui don't trip the unknown-key drop. The leading
+// `--` is added at serialization time.
+const COLOR_TOKEN_KEYS = [
+  'background',
+  'foreground',
+  'card',
+  'card-foreground',
+  'popover',
+  'popover-foreground',
+  'primary',
+  'primary-foreground',
+  'secondary',
+  'secondary-foreground',
+  'muted',
+  'muted-foreground',
+  'accent',
+  'accent-foreground',
+  'destructive',
+  'destructive-foreground',
+  'border',
+  'input',
+  'ring',
+  'avatar-background',
+  'nav-background',
+  'nav-border',
+  'nav-button-active-bg',
+  'nav-button-active-text',
+  'nav-foreground',
+  'success',
+  'warning',
+  'warning-foreground',
+  'info',
+  'info-foreground',
+  'sidebar',
+  'sidebar-foreground',
+  'sidebar-primary',
+  'sidebar-primary-foreground',
+  'sidebar-accent',
+  'sidebar-accent-foreground',
+  'sidebar-border',
+  'sidebar-ring',
+] as const
+
+type ColorTokenKey = (typeof COLOR_TOKEN_KEYS)[number]
+
+const COLOR_TOKEN_KEY_SET: ReadonlySet<string> = new Set(COLOR_TOKEN_KEYS)
+
+// Longest plausible CSS color value (e.g. `oklch(0.5849 0.095 159.91 / 100%)`)
+// is well under 50 chars; 100 is generous enough to absorb formatting variation
+// while still capping pathological input that could explode the `<style>` body.
+const MAX_VALUE_LENGTH = 100
+
+// Reject any character or sequence that could close the property/declaration
+// or open a comment inside the emitted `<style>` block. `url(` is blocked as
+// defense-in-depth.
+const UNSAFE_VALUE_PATTERN = /[;{}<>\n\r\\]|\/\*|\*\/|url\(/i
+
+function isColorTokenKey(key: string): key is ColorTokenKey {
+  return COLOR_TOKEN_KEY_SET.has(key)
+}
+
+function isValidColorTokenValue(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= MAX_VALUE_LENGTH &&
+    !UNSAFE_VALUE_PATTERN.test(value)
+  )
+}
+
+// Render one mode's color token map as a CSS declaration list (no surrounding
+// selector). Unknown keys and unsafe values are dropped silently — partial
+// output is preferable to no override at all.
+export function tokensToCssDeclarations(
+  tokens: ColorTokens['light'] | undefined
+): string {
+  if (!tokens) return ''
+  const parts: string[] = []
+  for (const [key, value] of Object.entries(tokens)) {
+    if (!isColorTokenKey(key)) continue
+    if (!isValidColorTokenValue(value)) continue
+    parts.push(`--${key}: ${value};`)
+  }
+  return parts.join(' ')
+}
+
+// Selector choice — `:root:not(.dark)` for light, `.dark` for dark — matches
+// cloud-ui. The `:not(.dark)` is load-bearing: a bare `:root` would tie with
+// `.dark` on specificity and leak light values into dark mode via source
+// order. `:root:not(.dark)` doesn't match in dark mode, so the cascade picks
+// up the default `.dark` declaration in `renderer/src/index.css`.
+export function colorTokensToStyleContent(
+  tokens: ColorTokens | null | undefined
+): string {
+  if (!tokens) return ''
+  const lightDecls = tokensToCssDeclarations(tokens.light)
+  const darkDecls = tokensToCssDeclarations(tokens.dark)
+  const blocks: string[] = []
+  if (lightDecls) blocks.push(`:root:not(.dark) { ${lightDecls} }`)
+  if (darkDecls) blocks.push(`.dark { ${darkDecls} }`)
+  return blocks.join(' ')
+}
diff --git a/common/branding/schema.ts b/common/branding/schema.ts
new file mode 100644
index 000000000..7a1bca9c5
--- /dev/null
+++ b/common/branding/schema.ts
@@ -0,0 +1,35 @@
+import { z } from 'zod/v4'
+
+// SEP#725 — Shape of the JSON at the branding config path. Matches cloud-ui's
+// `BrandingConfig` (`sep/enterprise/toolhive-cloud-ui/src/lib/branding-config.ts`).
+// Field names are snake-cased so operators write idiomatic JSON. All fields
+// are optional; missing fields fall back to the bundled defaults.
+//
+// Studio currently consumes only `design_tokens.colors`; the non-color fields
+// (`app_name`, `logo_url`, `favicon_url`) are parsed for forward compatibility
+// but not yet applied — see the "Non-color fields" deferred decision in
+// scratchpad / SEP#725.
+
+const colorMap = z.record(z.string(), z.string())
+
+export const brandingConfigSchema = z
+  .object({
+    app_name: z.string().optional(),
+    logo_url: z.string().optional(),
+    favicon_url: z.string().optional(),
+    design_tokens: z
+      .object({
+        colors: z
+          .object({
+            light: colorMap.optional(),
+            dark: colorMap.optional(),
+          })
+          .optional(),
+      })
+      .optional(),
+  })
+  // Reject unknown top-level keys silently rather than failing — operators
+  // may pass through extra fields the config server adds in the future.
+  .loose()
+
+export type BrandingConfig = z.infer<typeof brandingConfigSchema>
diff --git a/main/src/branding/__tests__/load.test.ts b/main/src/branding/__tests__/load.test.ts
new file mode 100644
index 000000000..e97f15e03
--- /dev/null
+++ b/main/src/branding/__tests__/load.test.ts
@@ -0,0 +1,144 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { mockReadFile } = vi.hoisted(() => ({ mockReadFile: vi.fn() }))
+
+vi.mock('node:fs/promises', () => ({
+  default: { readFile: mockReadFile },
+  readFile: mockReadFile,
+}))
+
+vi.mock('../../logger', () => ({
+  default: {
+    warn: vi.fn(),
+    info: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  },
+}))
+
+import { loadBrandingConfig, getBrandingCss } from '../load'
+
+const FAKE_PATH = '/fake/branding.json'
+
+function enoent(): NodeJS.ErrnoException {
+  const err = new Error('ENOENT: no such file') as NodeJS.ErrnoException
+  err.code = 'ENOENT'
+  return err
+}
+
+describe('loadBrandingConfig', () => {
+  beforeEach(() => {
+    mockReadFile.mockReset()
+  })
+
+  it('returns null when the file does not exist (ENOENT)', async () => {
+    mockReadFile.mockRejectedValueOnce(enoent())
+    await expect(loadBrandingConfig(FAKE_PATH)).resolves.toBeNull()
+  })
+
+  it('returns null on other read errors', async () => {
+    mockReadFile.mockRejectedValueOnce(new Error('EACCES'))
+    await expect(loadBrandingConfig(FAKE_PATH)).resolves.toBeNull()
+  })
+
+  it('returns null when content is not valid JSON', async () => {
+    mockReadFile.mockResolvedValueOnce('{ not json ')
+    await expect(loadBrandingConfig(FAKE_PATH)).resolves.toBeNull()
+  })
+
+  it('returns null when content is not an object', async () => {
+    mockReadFile.mockResolvedValueOnce('["array", "instead"]')
+    await expect(loadBrandingConfig(FAKE_PATH)).resolves.toBeNull()
+  })
+
+  it('returns the parsed config for a minimal valid file', async () => {
+    mockReadFile.mockResolvedValueOnce(
+      JSON.stringify({
+        design_tokens: { colors: { light: { primary: '#ff6600' } } },
+      })
+    )
+    const cfg = await loadBrandingConfig(FAKE_PATH)
+    expect(cfg).toEqual({
+      design_tokens: { colors: { light: { primary: '#ff6600' } } },
+    })
+  })
+
+  it('passes through forward-compat non-color fields without consuming them', async () => {
+    mockReadFile.mockResolvedValueOnce(
+      JSON.stringify({
+        app_name: 'Acme',
+        logo_url: 'https://cdn.example.com/logo.svg',
+        design_tokens: { colors: { light: { primary: '#abc' } } },
+      })
+    )
+    const cfg = await loadBrandingConfig(FAKE_PATH)
+    expect(cfg?.app_name).toBe('Acme')
+    expect(cfg?.logo_url).toBe('https://cdn.example.com/logo.svg')
+  })
+
+  it('returns null when shape is fundamentally wrong (colors not an object)', async () => {
+    mockReadFile.mockResolvedValueOnce(
+      JSON.stringify({ design_tokens: { colors: 'oops' } })
+    )
+    await expect(loadBrandingConfig(FAKE_PATH)).resolves.toBeNull()
+  })
+})
+
+describe('getBrandingCss', () => {
+  beforeEach(() => {
+    mockReadFile.mockReset()
+  })
+
+  it('returns empty string when there is no config file', async () => {
+    mockReadFile.mockRejectedValueOnce(enoent())
+    await expect(getBrandingCss(FAKE_PATH)).resolves.toBe('')
+  })
+
+  it('returns empty string when the config has no color overrides', async () => {
+    mockReadFile.mockResolvedValueOnce(JSON.stringify({ app_name: 'Acme' }))
+    await expect(getBrandingCss(FAKE_PATH)).resolves.toBe('')
+  })
+
+  it('serializes light + dark overrides into the cloud-ui selector shape', async () => {
+    mockReadFile.mockResolvedValueOnce(
+      JSON.stringify({
+        design_tokens: {
+          colors: {
+            light: { 'nav-background': '#c2185b' },
+            dark: { 'nav-background': '#4a0d33' },
+          },
+        },
+      })
+    )
+    await expect(getBrandingCss(FAKE_PATH)).resolves.toBe(
+      ':root:not(.dark) { --nav-background: #c2185b; } ' +
+        '.dark { --nav-background: #4a0d33; }'
+    )
+  })
+
+  it('drops unknown token keys silently', async () => {
+    mockReadFile.mockResolvedValueOnce(
+      JSON.stringify({
+        design_tokens: {
+          colors: {
+            light: { primary: '#abc', 'not-a-real-token': '#fff' },
+          },
+        },
+      })
+    )
+    await expect(getBrandingCss(FAKE_PATH)).resolves.toBe(
+      ':root:not(.dark) { --primary: #abc; }'
+    )
+  })
+
+  it('drops values that fail sanitization', async () => {
+    mockReadFile.mockResolvedValueOnce(
+      JSON.stringify({
+        design_tokens: {
+          colors: { light: { primary: '#abc; background: url(x)' } },
+        },
+      })
+    )
+    await expect(getBrandingCss(FAKE_PATH)).resolves.toBe('')
+  })
+})
diff --git a/main/src/branding/load.ts b/main/src/branding/load.ts
new file mode 100644
index 000000000..21d6dee38
--- /dev/null
+++ b/main/src/branding/load.ts
@@ -0,0 +1,73 @@
+import { readFile } from 'node:fs/promises'
+import {
+  brandingConfigSchema,
+  type BrandingConfig,
+} from '@common/branding/schema'
+import { colorTokensToStyleContent } from '@common/branding/color-tokens'
+import log from '../logger'
+
+// SEP#725 — Load the operator-supplied branding config and serialize the
+// color-token overrides into a CSS string the renderer can inject verbatim
+// into a `<style>` tag.
+//
+// One-shot read at boot. To pick up edits to the JSON without an app
+// restart, replace this with an `fs.watch`-driven emitter that pushes
+// updates to the renderer over IPC — out of scope for the initial cut
+// (see scratchpad "Hot reload vs restart-required" decision).
+//
+// Returns `null` on any read / parse / shape error. All failure modes are
+// logged at warn level so a broken config surfaces in studio logs instead of
+// silently falling back to the default palette.
+
+export async function loadBrandingConfig(
+  filePath: string
+): Promise<BrandingConfig | null> {
+  let raw: string
+  try {
+    raw = await readFile(filePath, 'utf-8')
+  } catch (err) {
+    // ENOENT is the common "operator didn't configure anything" case — quiet.
+    if (
+      err instanceof Error &&
+      'code' in err &&
+      (err as NodeJS.ErrnoException).code === 'ENOENT'
+    ) {
+      return null
+    }
+    log.warn(
+      `[branding] failed to read ${filePath}: ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    )
+    return null
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    log.warn(
+      `[branding] invalid JSON in ${filePath}: ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    )
+    return null
+  }
+
+  const result = brandingConfigSchema.safeParse(parsed)
+  if (!result.success) {
+    log.warn(
+      `[branding] config at ${filePath} did not match schema: ${result.error.message}`
+    )
+    return null
+  }
+  return result.data
+}
+
+// Composes the loader + the renderer-facing CSS emitter. Returns an empty
+// string if there is no config, or no color overrides in the config, so the
+// renderer can unconditionally inject the result into a `<style>` block.
+export async function getBrandingCss(filePath: string): Promise<string> {
+  const config = await loadBrandingConfig(filePath)
+  return colorTokensToStyleContent(config?.design_tokens?.colors)
+}
diff --git a/main/src/branding/paths.ts b/main/src/branding/paths.ts
new file mode 100644
index 000000000..db4c3394a
--- /dev/null
+++ b/main/src/branding/paths.ts
@@ -0,0 +1,23 @@
+import path from 'node:path'
+import { app } from 'electron'
+
+// SEP#725 — Resolve the branding config file path.
+//
+// Single override file. Env-var override matches cloud-ui's `BRANDING_CONFIG_PATH`
+// for muscle memory. Default: `<userData>/branding-0.json` — per-OS-correct
+// via Electron (`~/Library/Application Support/...` on macOS, `%APPDATA%/...`
+// on Windows, `~/.config/...` on Linux).
+//
+// The `-0` suffix is future-proofing: layered `branding-N.json` precedence
+// (highest N wins, per the Slack design in thread 1778080552.563009) is out
+// of scope for MVP, but reserving the naming slot now lets a future loader
+// add layering without renaming operator-deployed files.
+
+const ENV_VAR = 'BRANDING_CONFIG_PATH'
+
+export function getBrandingConfigPath(): string {
+  return (
+    process.env[ENV_VAR] ??
+    path.join(app.getPath('userData'), 'branding-0.json')
+  )
+}
diff --git a/main/src/main-window.ts b/main/src/main-window.ts
index 06779a192..f9fee3328 100644
--- a/main/src/main-window.ts
+++ b/main/src/main-window.ts
@@ -4,6 +4,8 @@ import log from './logger'
 import { hideWindow } from './dock-utils'
 import { getQuittingState, getTray } from './app-state'
 import { pollWindowReady } from './util'
+import { getBrandingCss } from './branding/load'
+import { getBrandingConfigPath } from './branding/paths'
 
 // Forge environment variables
 declare const MAIN_WINDOW_VITE_DEV_SERVER_URL: string | undefined
@@ -155,6 +157,13 @@ export async function createMainWindow(
   try {
     log.info('Creating main window...')
 
+    // SEP#725 — load the operator-supplied branding CSS (if any) and pass it
+    // to the renderer via additionalArguments. Preload reads it from
+    // process.argv synchronously; renderer injects before React mounts so
+    // there's no FOUC. See preload/src/api/branding.ts.
+    const brandingCss = await getBrandingCss(getBrandingConfigPath())
+    const brandingArg = `--branding-css=${Buffer.from(brandingCss, 'utf-8').toString('base64')}`
+
     const windowOptions = {
       width: options.width || DEFAULT_WINDOW_WIDTH,
       height: options.height || DEFAULT_WINDOW_HEIGHT,
@@ -164,6 +173,7 @@ export async function createMainWindow(
         contextIsolation: true,
         preload: path.join(__dirname, 'preload.js'),
         webSecurity: !isDevelopment,
+        additionalArguments: [brandingArg],
       },
       ...getPlatformSpecificWindowOptions(),
     }
diff --git a/package.json b/package.json
index eb6078ed6..4124f7d40 100644
--- a/package.json
+++ b/package.json
@@ -11,6 +11,7 @@
   "scripts": {
     "start": "electron-forge start",
     "start:inspect": "tsx scripts/start-inspect.ts",
+    "start:customTheme": "tsx scripts/start-custom-theme.ts",
     "rebuild": "electron-rebuild -f -w better-sqlite3",
     "postinstall": "pnpm run rebuild",
     "e2e": "pnpm package && pnpm e2e:prebuilt",
diff --git a/preload/src/api/__tests__/branding.test.ts b/preload/src/api/__tests__/branding.test.ts
new file mode 100644
index 000000000..19ddd8e07
--- /dev/null
+++ b/preload/src/api/__tests__/branding.test.ts
@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+const ARG_PREFIX = '--branding-css='
+
+describe('preload branding API', () => {
+  let originalArgv: string[]
+
+  beforeEach(() => {
+    originalArgv = process.argv
+    vi.resetModules()
+  })
+
+  afterEach(() => {
+    process.argv = originalArgv
+  })
+
+  async function loadFresh(argv: string[]) {
+    process.argv = argv
+    return import('../branding')
+  }
+
+  it('exposes an empty string when the branding arg is absent', async () => {
+    const mod = await loadFresh(['electron', 'app.js'])
+    expect(mod.brandingApi.branding.css).toBe('')
+  })
+
+  it('exposes an empty string when the branding arg is empty', async () => {
+    const mod = await loadFresh(['electron', 'app.js', ARG_PREFIX])
+    expect(mod.brandingApi.branding.css).toBe('')
+  })
+
+  it('decodes a base64-encoded CSS payload', async () => {
+    const css = ':root:not(.dark) { --primary: oklch(0.5 0.2 340); }'
+    const encoded = Buffer.from(css, 'utf-8').toString('base64')
+    const mod = await loadFresh([
+      'electron',
+      'app.js',
+      `${ARG_PREFIX}${encoded}`,
+    ])
+    expect(mod.brandingApi.branding.css).toBe(css)
+  })
+
+  it('handles multi-byte unicode in the CSS payload', async () => {
+    const css = '/* théme — 中文 */ .dark { --primary: #c2185b; }'
+    const encoded = Buffer.from(css, 'utf-8').toString('base64')
+    const mod = await loadFresh([
+      'electron',
+      'app.js',
+      `${ARG_PREFIX}${encoded}`,
+    ])
+    expect(mod.brandingApi.branding.css).toBe(css)
+  })
+})
diff --git a/preload/src/api/branding.ts b/preload/src/api/branding.ts
new file mode 100644
index 000000000..b4128c285
--- /dev/null
+++ b/preload/src/api/branding.ts
@@ -0,0 +1,39 @@
+// SEP#725 — Brand color overrides.
+//
+// Main process reads the operator's `branding-0.json`, serializes it to a CSS
+// string, and passes it to the renderer process via `webPreferences.additional
+// Arguments`. Preload picks it out of `process.argv`, decodes it, and exposes
+// it as a string constant on `electronAPI.branding.css`. The renderer injects
+// it into `<head>` synchronously before mounting React — no IPC roundtrip,
+// no FOUC.
+//
+// Argument format: `--branding-css=<base64-encoded-utf-8>`. Base64 keeps the
+// CSS opaque to shell / argv quoting concerns; an empty CSS string is encoded
+// as the empty payload. If the arg isn't present (e.g. tests, a window not
+// created by `createMainWindow`), we expose an empty string.
+
+const ARG_PREFIX = '--branding-css='
+
+function readBrandingCss(): string {
+  const arg = process.argv.find((a) => a.startsWith(ARG_PREFIX))
+  if (!arg) return ''
+  const encoded = arg.slice(ARG_PREFIX.length)
+  if (!encoded) return ''
+  try {
+    return Buffer.from(encoded, 'base64').toString('utf-8')
+  } catch {
+    return ''
+  }
+}
+
+export const brandingApi = {
+  branding: {
+    css: readBrandingCss(),
+  },
+} as const
+
+export interface BrandingAPI {
+  branding: {
+    css: string
+  }
+}
diff --git a/preload/src/preload.ts b/preload/src/preload.ts
index 96cf20d9f..9cd9de81d 100644
--- a/preload/src/preload.ts
+++ b/preload/src/preload.ts
@@ -4,6 +4,7 @@
 import { contextBridge } from 'electron'
 import { appApi, type AppAPI } from './api/app'
 import { autoUpdateApi, type AutoUpdateAPI } from './api/auto-update'
+import { brandingApi, type BrandingAPI } from './api/branding'
 import { chatApi, type ChatAPI } from './api/chat'
 import { cliApi, type CliAPI } from './api/cli'
 import { darkModeApi, type DarkModeAPI } from './api/dark-mode'
@@ -28,7 +29,8 @@ export type ElectronAPI = AppAPI &
   CliAPI &
   UiPreferencesAPI &
   UtilsAPI &
-  EventsAPI
+  EventsAPI &
+  BrandingAPI
 
 const electronAPI = {
   ...appApi,
@@ -44,6 +46,7 @@ const electronAPI = {
   ...uiPreferencesApi,
   ...utilsApi,
   ...eventsApi,
+  ...brandingApi,
 } satisfies ElectronAPI
 
 contextBridge.exposeInMainWorld('electronAPI', electronAPI)
diff --git a/renderer/src/common/mocks/electronAPI.ts b/renderer/src/common/mocks/electronAPI.ts
index 6a0f20fd7..caa05f85b 100644
--- a/renderer/src/common/mocks/electronAPI.ts
+++ b/renderer/src/common/mocks/electronAPI.ts
@@ -34,6 +34,7 @@ function createElectronStub(): Partial<ElectronAPI> {
       }),
       set: vi.fn().mockResolvedValue(true),
     } as ElectronAPI['darkMode'],
+    branding: { css: '' } as ElectronAPI['branding'],
     featureFlags: {
       get: vi.fn().mockResolvedValue(false),
       enable: vi.fn().mockResolvedValue(undefined),
diff --git a/renderer/src/index.css b/renderer/src/index.css
index 5f607b4a4..0f503afb9 100644
--- a/renderer/src/index.css
+++ b/renderer/src/index.css
@@ -58,9 +58,14 @@
   --color-nav-border: var(--nav-border);
   --color-nav-button-active-bg: var(--nav-button-active-bg);
   --color-nav-button-active-text: var(--nav-button-active-text);
+  --color-nav-foreground: var(--nav-foreground);
 
   /* Status colors */
   --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
 
   /* Brand colors */
   --color-brand-green-light: var(--brand-green-light);
@@ -115,6 +120,13 @@
 
   /* Status colors */
   --success: oklch(0.5849 0.095 159.91);
+  --warning: oklch(0.75 0.17 80);
+  --warning-foreground: oklch(0.2 0.05 80);
+  --info: oklch(0.55 0.2 240);
+  --info-foreground: oklch(0.98 0 0);
+
+  /* Nav foreground (text/icons painted over --nav-background) */
+  --nav-foreground: oklch(0.985 0 0);
 
   /* Brand colors */
   --brand-green-light: oklch(0.9522 0.0524 164.2);
@@ -168,6 +180,13 @@
 
   /* Status colors */
   --success: oklch(0.724 0.1091 160.66);
+  --warning: oklch(0.8 0.16 80);
+  --warning-foreground: oklch(0.2 0.05 80);
+  --info: oklch(0.7 0.18 240);
+  --info-foreground: oklch(0.15 0.05 240);
+
+  /* Nav foreground */
+  --nav-foreground: oklch(0.985 0 0);
 
   /* Brand colors */
   --brand-green-light: oklch(0.3262 0.0342 161.99);
diff --git a/renderer/src/renderer.tsx b/renderer/src/renderer.tsx
index 3c95d29d4..28bdfda0b 100644
--- a/renderer/src/renderer.tsx
+++ b/renderer/src/renderer.tsx
@@ -18,6 +18,20 @@ import './common/lib/feature-flags'
 // Import OS design devtools to bind OsDesign.setMac/setWindows/reset to window
 import './common/lib/os-design'
 
+// SEP#725 — Apply operator-supplied brand color overrides before mounting
+// React, so the first paint shows the branded palette and there's no FOUC.
+// The CSS is computed in the main process from `branding-0.json` and forwarded
+// to preload via webPreferences.additionalArguments. See:
+//   - main/src/main-window.ts (load + pass)
+//   - preload/src/api/branding.ts (decode + expose)
+const brandingCss = window.electronAPI?.branding?.css
+if (brandingCss) {
+  const styleEl = document.createElement('style')
+  styleEl.id = 'brand-theme'
+  styleEl.textContent = brandingCss
+  document.head.appendChild(styleEl)
+}
+
 initSentry()
 
 if (!window.electronAPI || !window.electronAPI.apiFetch) {
diff --git a/scripts/start-custom-theme.ts b/scripts/start-custom-theme.ts
new file mode 100644
index 000000000..b22253335
--- /dev/null
+++ b/scripts/start-custom-theme.ts
@@ -0,0 +1,38 @@
+#!/usr/bin/env tsx
+/**
+ * Dev helper: launch the app with the test theme at
+ * `branding-examples/test-theme.json` so we can verify that every themeable
+ * surface in studio is actually wired to the branding override. The theme
+ * uses a deliberately-distinct wine/coral/gold palette unmistakable from
+ * studio's defaults. Cross-platform env-var setting (vs. inline `KEY=val` in
+ * package.json, which breaks on Windows cmd.exe).
+ */
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const repoRoot = path.join(__dirname, '..')
+const themePath = path.join(repoRoot, 'branding-examples', 'test-theme.json')
+
+const child = spawn('pnpm', ['exec', 'electron-forge', 'start'], {
+  cwd: repoRoot,
+  stdio: 'inherit',
+  shell: true,
+  env: {
+    ...process.env,
+    BRANDING_CONFIG_PATH: themePath,
+    FORCE_COLOR: process.env.FORCE_COLOR ?? '1',
+  },
+})
+
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  else process.exit(code ?? 0)
+})
+
+for (const sig of ['SIGINT', 'SIGTERM'] as const) {
+  process.on(sig, () => {
+    if (!child.killed) child.kill(sig)
+  })
+}
diff --git a/vitest.setup.ts b/vitest.setup.ts
index 0b4f42b8b..9de5e4f22 100644
--- a/vitest.setup.ts
+++ b/vitest.setup.ts
@@ -70,6 +70,7 @@ beforeAll(() => {
         }),
         set: vi.fn().mockResolvedValue(true),
       } as unknown as ElectronAPI['darkMode'],
+      branding: { css: '' } as ElectronAPI['branding'],
       featureFlags: {
         get: vi.fn().mockResolvedValue(false),
         enable: vi.fn().mockResolvedValue(undefined),

From df977b0ebf38e7e0d437bf922cc144d4460c4ff7 Mon Sep 17 00:00:00 2001
From: Daniel Kantor <kd@stacklok.com>
Date: Fri, 15 May 2026 20:01:47 +0200
Subject: [PATCH 2/6] add new tokens

---
 .../components/code-block-with-copy.tsx       |  2 +-
 .../components/custom-socket-banner.tsx       |  8 ++---
 .../components/error/technical-details.tsx    |  2 +-
 .../components/expert-consultation-banner.tsx | 12 ++++---
 .../components/layout/top-nav/index.tsx       |  5 +--
 .../layout/top-nav/nav-icon-button.tsx        |  4 +--
 .../layout/top-nav/window-controls.tsx        | 11 ++++--
 .../common/components/newsletter-modal.tsx    |  2 +-
 .../tabs/__tests__/settings-tabs.test.tsx     | 12 +++----
 .../settings/tabs/settings-tabs.tsx           |  2 +-
 .../components/ui/circular-status-icon.tsx    |  8 ++---
 renderer/src/common/components/ui/dialog.tsx  |  8 ++---
 renderer/src/common/components/ui/tabs.tsx    |  2 +-
 .../src/common/components/ui/textarea.tsx     |  9 ++---
 .../src/common/components/view-toggle.tsx     |  3 +-
 .../alert-error-fetching-editing-data.tsx     |  2 +-
 .../workloads/alert-error-form-submission.tsx |  4 +--
 .../workloads/link-error-discord.tsx          |  2 +-
 renderer/src/common/hooks/use-prompt.tsx      |  2 +-
 .../agents/components/agent-detail-page.tsx   |  2 +-
 .../chat-message/reasoning-component.tsx      |  2 +-
 .../chat-message/tool-call-component.tsx      | 35 ++++++++-----------
 .../components/dialog-provider-settings.tsx   | 12 +++----
 .../features/chat/components/error-alert.tsx  |  4 +--
 .../chat/components/mcp-tools-modal.tsx       |  2 +-
 .../tool-results/skill-build-result-card.tsx  | 11 +++---
 .../components/customize-tools-table.tsx      |  4 +--
 .../components/table-mcp-servers.tsx          |  2 +-
 .../mcp-servers/sub-pages/logs-page/index.tsx |  4 +--
 .../skills/components/build-detail-page.tsx   |  2 +-
 .../skills/components/skill-detail-page.tsx   |  2 +-
 31 files changed, 90 insertions(+), 92 deletions(-)

diff --git a/renderer/src/common/components/code-block-with-copy.tsx b/renderer/src/common/components/code-block-with-copy.tsx
index c6dbf4568..7d39eeb82 100644
--- a/renderer/src/common/components/code-block-with-copy.tsx
+++ b/renderer/src/common/components/code-block-with-copy.tsx
@@ -48,7 +48,7 @@ export function CodeBlockWithCopy({ code }: CodeBlockWithCopyProps) {
         title={copied ? 'Copied!' : 'Copy command'}
       >
         {copied ? (
-          <Check className="size-4 text-green-600" />
+          <Check className="text-success size-4" />
         ) : (
           <Copy className="size-4" />
         )}
diff --git a/renderer/src/common/components/custom-socket-banner.tsx b/renderer/src/common/components/custom-socket-banner.tsx
index 2d535a5f9..78a5c01f4 100644
--- a/renderer/src/common/components/custom-socket-banner.tsx
+++ b/renderer/src/common/components/custom-socket-banner.tsx
@@ -32,17 +32,15 @@ export function CustomSocketBanner() {
 
   return (
     <Alert
-      className="fixed bottom-4 left-1/2 z-50 w-auto max-w-[95vw]
-        -translate-x-1/2 border-yellow-200 bg-yellow-50 text-yellow-900
-        dark:border-yellow-800 dark:bg-yellow-950 dark:text-yellow-100"
+      className="border-warning/40 bg-warning/15 text-warning-foreground fixed
+        bottom-4 left-1/2 z-50 w-auto max-w-[95vw] -translate-x-1/2"
     >
       <AlertTriangle />
       <AlertDescription className="flex items-start gap-2">
         <div className="whitespace-nowrap">
           <span>Using external ToolHive at </span>
           <span
-            className="rounded bg-yellow-100 px-1 py-0.5 font-mono text-xs
-              dark:bg-yellow-900"
+            className="bg-warning/25 rounded px-1 py-0.5 font-mono text-xs"
             title={socketPath}
           >
             {socketPath}
diff --git a/renderer/src/common/components/error/technical-details.tsx b/renderer/src/common/components/error/technical-details.tsx
index 88db74df8..c6524452b 100644
--- a/renderer/src/common/components/error/technical-details.tsx
+++ b/renderer/src/common/components/error/technical-details.tsx
@@ -51,7 +51,7 @@ function CopyButton({ getText }: CopyButtonProps) {
       title={copied ? 'Copied!' : 'Copy error report'}
     >
       {copied ? (
-        <Check className="size-3.5 text-green-600" />
+        <Check className="text-success size-3.5" />
       ) : (
         <Copy className="size-3.5" />
       )}
diff --git a/renderer/src/common/components/expert-consultation-banner.tsx b/renderer/src/common/components/expert-consultation-banner.tsx
index 86f1ac5d0..fbc8581b2 100644
--- a/renderer/src/common/components/expert-consultation-banner.tsx
+++ b/renderer/src/common/components/expert-consultation-banner.tsx
@@ -189,7 +189,7 @@ function ExpertConsultationDialog({
               className="flex flex-col gap-3"
             >
               {errors.form && (
-                <p className="text-sm text-red-600">
+                <p className="text-destructive text-sm">
                   Something went wrong. Please try submitting via{' '}
                   <a
                     href={DEMO_URL}
@@ -219,7 +219,9 @@ function ExpertConsultationDialog({
                       text-foreground placeholder:text-brand-blue-dark/40"
                   />
                   {errors.firstname && (
-                    <p className="text-sm text-red-600">{errors.firstname}</p>
+                    <p className="text-destructive text-sm">
+                      {errors.firstname}
+                    </p>
                   )}
                 </div>
                 <div className="flex flex-col gap-1">
@@ -237,7 +239,9 @@ function ExpertConsultationDialog({
                       text-foreground placeholder:text-brand-blue-dark/40"
                   />
                   {errors.lastname && (
-                    <p className="text-sm text-red-600">{errors.lastname}</p>
+                    <p className="text-destructive text-sm">
+                      {errors.lastname}
+                    </p>
                   )}
                 </div>
               </div>
@@ -269,7 +273,7 @@ function ExpertConsultationDialog({
                     text-foreground placeholder:text-brand-blue-dark/40"
                 />
                 {errors.email && (
-                  <p className="text-sm text-red-600">{errors.email}</p>
+                  <p className="text-destructive text-sm">{errors.email}</p>
                 )}
               </div>
 
diff --git a/renderer/src/common/components/layout/top-nav/index.tsx b/renderer/src/common/components/layout/top-nav/index.tsx
index 877c8f707..55ce67258 100644
--- a/renderer/src/common/components/layout/top-nav/index.tsx
+++ b/renderer/src/common/components/layout/top-nav/index.tsx
@@ -50,7 +50,8 @@ function NavButton({ to, icon: Icon, children, isActive }: NavButtonProps) {
         'text-sm font-medium transition-colors',
         isActive
           ? 'bg-nav-button-active-bg text-nav-button-active-text'
-          : 'bg-transparent text-white/90 hover:bg-white/10 hover:text-white'
+          : `text-nav-foreground/90 hover:bg-nav-foreground/10
+            hover:text-nav-foreground bg-transparent`
       )}
     >
       <Icon className="size-4" />
@@ -208,7 +209,7 @@ export function TopNav({ isEnterprise = false, ...props }: TopNavProps) {
               <SettingsIcon className="size-5" />
               {showUpdateBadge && (
                 <span className="absolute -top-0.5 -right-0.5">
-                  <ArrowUpCircle className="size-3 fill-blue-500" />
+                  <ArrowUpCircle className="fill-info size-3" />
                 </span>
               )}
             </LinkViewTransition>
diff --git a/renderer/src/common/components/layout/top-nav/nav-icon-button.tsx b/renderer/src/common/components/layout/top-nav/nav-icon-button.tsx
index 0fc5c5419..63cabac78 100644
--- a/renderer/src/common/components/layout/top-nav/nav-icon-button.tsx
+++ b/renderer/src/common/components/layout/top-nav/nav-icon-button.tsx
@@ -16,8 +16,8 @@ export function NavIconButton({
       variant="ghost"
       size="icon"
       className={cn(
-        `rounded-full text-white/90 hover:bg-white/10 hover:text-white
-        dark:hover:bg-white/10`,
+        `text-nav-foreground/90 hover:bg-nav-foreground/10
+        hover:text-nav-foreground dark:hover:bg-nav-foreground/10 rounded-full`,
         isActive && 'bg-nav-button-active-bg text-nav-button-active-text',
         className
       )}
diff --git a/renderer/src/common/components/layout/top-nav/window-controls.tsx b/renderer/src/common/components/layout/top-nav/window-controls.tsx
index 2b962f6d5..ce237790c 100644
--- a/renderer/src/common/components/layout/top-nav/window-controls.tsx
+++ b/renderer/src/common/components/layout/top-nav/window-controls.tsx
@@ -37,11 +37,15 @@ export function WindowControls() {
   }
 
   return (
-    <div className="app-region-no-drag flex items-center gap-0 pr-2 text-white">
+    <div
+      className="text-nav-foreground app-region-no-drag flex items-center gap-0
+        pr-2"
+    >
       <Button
         variant="ghost"
         size="icon"
-        className="h-8 w-12 rounded-none hover:bg-white/10 hover:text-white"
+        className="hover:bg-nav-foreground/10 hover:text-nav-foreground h-8 w-12
+          rounded-none"
         onClick={handleMinimize}
       >
         <Minus className="size-4" />
@@ -49,7 +53,8 @@ export function WindowControls() {
       <Button
         variant="ghost"
         size="icon"
-        className="h-8 w-12 rounded-none hover:bg-white/10 hover:text-white"
+        className="hover:bg-nav-foreground/10 hover:text-nav-foreground h-8 w-12
+          rounded-none"
         onClick={handleMaximize}
       >
         {isMaximized ? (
diff --git a/renderer/src/common/components/newsletter-modal.tsx b/renderer/src/common/components/newsletter-modal.tsx
index 3fc9163dc..f9b870210 100644
--- a/renderer/src/common/components/newsletter-modal.tsx
+++ b/renderer/src/common/components/newsletter-modal.tsx
@@ -173,7 +173,7 @@ function NewsletterDialog({
                     )}
                   </Button>
                 </div>
-                {error && <p className="text-sm text-red-600">{error}</p>}
+                {error && <p className="text-destructive text-sm">{error}</p>}
               </div>
 
               <PrivacyFooter>
diff --git a/renderer/src/common/components/settings/tabs/__tests__/settings-tabs.test.tsx b/renderer/src/common/components/settings/tabs/__tests__/settings-tabs.test.tsx
index d22e3076b..c87f5f0be 100644
--- a/renderer/src/common/components/settings/tabs/__tests__/settings-tabs.test.tsx
+++ b/renderer/src/common/components/settings/tabs/__tests__/settings-tabs.test.tsx
@@ -194,7 +194,7 @@ describe('SettingsTabs', () => {
     const versionTab = screen.getByRole('tab', { name: /Version/i })
     expect(versionTab).toBeVisible()
 
-    const updateIcon = versionTab.querySelector('svg.text-blue-500')
+    const updateIcon = versionTab.querySelector('svg.text-info')
     expect(updateIcon).toBeInTheDocument()
   })
 
@@ -217,7 +217,7 @@ describe('SettingsTabs', () => {
     const versionTab = screen.getByRole('tab', { name: /Version/i })
     expect(versionTab).toBeVisible()
 
-    const updateIcon = versionTab.querySelector('svg.text-blue-500')
+    const updateIcon = versionTab.querySelector('svg.text-info')
     expect(updateIcon).not.toBeInTheDocument()
   })
 
@@ -240,7 +240,7 @@ describe('SettingsTabs', () => {
     const versionTab = screen.getByRole('tab', { name: /Version/i })
     expect(versionTab).toBeVisible()
 
-    const updateIcon = versionTab.querySelector('svg.text-blue-500')
+    const updateIcon = versionTab.querySelector('svg.text-info')
     expect(updateIcon).not.toBeInTheDocument()
   })
 
@@ -285,9 +285,7 @@ describe('SettingsTabs', () => {
     const generalTab = screen.getByRole('tab', { name: 'General' })
     const logsTab = screen.getByRole('tab', { name: 'Logs' })
 
-    expect(
-      generalTab.querySelector('svg.text-blue-500')
-    ).not.toBeInTheDocument()
-    expect(logsTab.querySelector('svg.text-blue-500')).not.toBeInTheDocument()
+    expect(generalTab.querySelector('svg.text-info')).not.toBeInTheDocument()
+    expect(logsTab.querySelector('svg.text-info')).not.toBeInTheDocument()
   })
 })
diff --git a/renderer/src/common/components/settings/tabs/settings-tabs.tsx b/renderer/src/common/components/settings/tabs/settings-tabs.tsx
index c2ccfc7ad..70fb1a60c 100644
--- a/renderer/src/common/components/settings/tabs/settings-tabs.tsx
+++ b/renderer/src/common/components/settings/tabs/settings-tabs.tsx
@@ -74,7 +74,7 @@ export function SettingsTabs({ defaultTab }: SettingsTabsProps) {
                 {tab.label}
                 {tab.value === 'version' && isNewVersionAvailable && (
                   <div className="bg-background rounded-full">
-                    <ArrowUpCircle className="size-4 text-blue-500" />
+                    <ArrowUpCircle className="text-info size-4" />
                     <span className="sr-only">Update available</span>
                   </div>
                 )}
diff --git a/renderer/src/common/components/ui/circular-status-icon.tsx b/renderer/src/common/components/ui/circular-status-icon.tsx
index d8645f199..ab979e4de 100644
--- a/renderer/src/common/components/ui/circular-status-icon.tsx
+++ b/renderer/src/common/components/ui/circular-status-icon.tsx
@@ -7,10 +7,10 @@ const circularStatusIconVariants = cva(
   {
     variants: {
       variant: {
-        default: 'border-gray-100 bg-gray-500',
-        destructive: 'border-red-100 bg-red-500',
-        success: 'border-green-100 bg-green-500',
-        warning: 'border-yellow-100 bg-yellow-500',
+        default: 'bg-muted-foreground border-muted',
+        destructive: 'bg-destructive border-destructive/20',
+        success: 'bg-success border-success/20',
+        warning: 'bg-warning border-warning/20',
       },
     },
     defaultVariants: {
diff --git a/renderer/src/common/components/ui/dialog.tsx b/renderer/src/common/components/ui/dialog.tsx
index e65b9c9e2..688d6bd15 100644
--- a/renderer/src/common/components/ui/dialog.tsx
+++ b/renderer/src/common/components/ui/dialog.tsx
@@ -63,10 +63,10 @@ function DialogContent({
           `dark:bg-card data-[state=open]:animate-in
           data-[state=closed]:animate-out data-[state=closed]:fade-out-0
           data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95
-          data-[state=open]:zoom-in-95 app-region-no-drag fixed top-[50%]
-          left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%]
-          translate-y-[-50%] gap-4 rounded-lg border bg-white p-6 shadow-lg
-          duration-200 sm:max-w-lg`,
+          data-[state=open]:zoom-in-95 app-region-no-drag bg-popover fixed
+          top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)]
+          translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6
+          shadow-lg duration-200 sm:max-w-lg`,
           className
         )}
         {...props}
diff --git a/renderer/src/common/components/ui/tabs.tsx b/renderer/src/common/components/ui/tabs.tsx
index ff2ae8222..78e31559c 100644
--- a/renderer/src/common/components/ui/tabs.tsx
+++ b/renderer/src/common/components/ui/tabs.tsx
@@ -27,7 +27,7 @@ const tabsListVariants = cva(
     variants: {
       variant: {
         default: 'bg-muted h-9 rounded-lg p-[3px]',
-        pill: 'h-auto rounded-full bg-zinc-200 p-1 dark:bg-zinc-800',
+        pill: 'bg-muted h-auto rounded-full p-1',
       },
     },
     defaultVariants: {
diff --git a/renderer/src/common/components/ui/textarea.tsx b/renderer/src/common/components/ui/textarea.tsx
index a4b0e5475..94a899319 100644
--- a/renderer/src/common/components/ui/textarea.tsx
+++ b/renderer/src/common/components/ui/textarea.tsx
@@ -10,10 +10,11 @@ function Textarea({ className, ...props }: React.ComponentProps<'textarea'>) {
         `border-input placeholder:text-muted-foreground
         focus-visible:border-ring focus-visible:ring-ring/50
         aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40
-        aria-invalid:border-destructive dark:bg-card flex field-sizing-content
-        min-h-16 w-full rounded-md border bg-white px-3 py-2 text-base shadow-xs
-        transition-[color,box-shadow] outline-none focus-visible:ring-[3px]
-        disabled:cursor-not-allowed disabled:opacity-50 md:text-sm`,
+        aria-invalid:border-destructive bg-input dark:bg-card flex
+        field-sizing-content min-h-16 w-full rounded-md border px-3 py-2
+        text-base shadow-xs transition-[color,box-shadow] outline-none
+        focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50
+        md:text-sm`,
         className
       )}
       {...props}
diff --git a/renderer/src/common/components/view-toggle.tsx b/renderer/src/common/components/view-toggle.tsx
index 328820e72..61d7ac2f9 100644
--- a/renderer/src/common/components/view-toggle.tsx
+++ b/renderer/src/common/components/view-toggle.tsx
@@ -31,8 +31,7 @@ export function ViewToggle({
       }}
       aria-label={ariaLabel}
       className={cn(
-        `inline-flex h-auto items-center gap-1 rounded-full bg-zinc-200 p-1
-        dark:bg-zinc-800`,
+        'bg-muted inline-flex h-auto items-center gap-1 rounded-full p-1',
         className
       )}
     >
diff --git a/renderer/src/common/components/workloads/alert-error-fetching-editing-data.tsx b/renderer/src/common/components/workloads/alert-error-fetching-editing-data.tsx
index 5c4d4d76d..753c29e8c 100644
--- a/renderer/src/common/components/workloads/alert-error-fetching-editing-data.tsx
+++ b/renderer/src/common/components/workloads/alert-error-fetching-editing-data.tsx
@@ -12,7 +12,7 @@ export function AlertErrorFetchingEditingData() {
         Something went wrong while retrieving the data of the server
       </AlertTitle>
       <AlertDescription>
-        <p className="text-red-300">
+        <p className="text-destructive">
           Close the dialog and try again. <br />
           If issues persist, contact the ToolHive team via <LinkErrorDiscord />.
         </p>
diff --git a/renderer/src/common/components/workloads/alert-error-form-submission.tsx b/renderer/src/common/components/workloads/alert-error-form-submission.tsx
index ba3bd6fe2..bb43cbb3d 100644
--- a/renderer/src/common/components/workloads/alert-error-form-submission.tsx
+++ b/renderer/src/common/components/workloads/alert-error-form-submission.tsx
@@ -42,7 +42,7 @@ export function AlertErrorFormSubmission({
         </Button>
       </AlertTitle>
       <AlertDescription>
-        <p className="text-red-300">
+        <p className="text-destructive">
           {isErrorSecrets && 'Failed to create secrets for the server. '}
           Check the configuration and try again. <br />
           If issues persist, contact the ToolHive team via <LinkErrorDiscord />.
@@ -50,7 +50,7 @@ export function AlertErrorFormSubmission({
         {!isErrorSecrets && (
           <>
             <Separator className="my-2" />
-            <p className="font-mono text-xs text-gray-300">{error}</p>
+            <p className="text-muted-foreground font-mono text-xs">{error}</p>
           </>
         )}
       </AlertDescription>
diff --git a/renderer/src/common/components/workloads/link-error-discord.tsx b/renderer/src/common/components/workloads/link-error-discord.tsx
index a363674b5..63322ade5 100644
--- a/renderer/src/common/components/workloads/link-error-discord.tsx
+++ b/renderer/src/common/components/workloads/link-error-discord.tsx
@@ -6,7 +6,7 @@ export function LinkErrorDiscord() {
       href={DISCORD_URL}
       target="_blank"
       rel="noopener noreferrer"
-      className="text-red-300 underline hover:text-red-200"
+      className="text-destructive hover:text-destructive/80 underline"
     >
       Discord
     </a>
diff --git a/renderer/src/common/hooks/use-prompt.tsx b/renderer/src/common/hooks/use-prompt.tsx
index c6924ab5e..cb198f2c3 100644
--- a/renderer/src/common/hooks/use-prompt.tsx
+++ b/renderer/src/common/hooks/use-prompt.tsx
@@ -92,7 +92,7 @@ export function generateSimplePrompt({
             />
           )}
           {form.formState.errors.value && (
-            <p className="mt-1 text-sm text-red-500">
+            <p className="text-destructive mt-1 text-sm">
               {form.formState.errors.value.message}
             </p>
           )}
diff --git a/renderer/src/features/agents/components/agent-detail-page.tsx b/renderer/src/features/agents/components/agent-detail-page.tsx
index a85bb9b0c..d7cc8a8ce 100644
--- a/renderer/src/features/agents/components/agent-detail-page.tsx
+++ b/renderer/src/features/agents/components/agent-detail-page.tsx
@@ -185,7 +185,7 @@ export function AgentDetailPage({ agent }: { agent: AgentConfig }) {
             System prompt
           </h4>
           <div
-            className="border-border mb-8 rounded-2xl border bg-white p-6
+            className="border-border bg-card mb-8 rounded-2xl border p-6
               dark:bg-transparent"
           >
             {agent.instructions.trim().length > 0 ? (
diff --git a/renderer/src/features/chat/components/chat-message/reasoning-component.tsx b/renderer/src/features/chat/components/chat-message/reasoning-component.tsx
index 1f8d99933..c2dc15c29 100644
--- a/renderer/src/features/chat/components/chat-message/reasoning-component.tsx
+++ b/renderer/src/features/chat/components/chat-message/reasoning-component.tsx
@@ -35,7 +35,7 @@ function ReasoningComponentImpl({
   return (
     <div className="bg-card mb-3 rounded-lg border p-3">
       <div className="mb-2 flex items-center gap-2">
-        <Brain className="h-4 w-4 text-purple-500" />
+        <Brain className="text-info h-4 w-4" />
         <span className="text-foreground text-sm font-medium">
           AI Reasoning
         </span>
diff --git a/renderer/src/features/chat/components/chat-message/tool-call-component.tsx b/renderer/src/features/chat/components/chat-message/tool-call-component.tsx
index 74d476dec..0b913ecd5 100644
--- a/renderer/src/features/chat/components/chat-message/tool-call-component.tsx
+++ b/renderer/src/features/chat/components/chat-message/tool-call-component.tsx
@@ -51,22 +51,22 @@ function ToolCallComponentImpl({
   return (
     <div className="bg-card mb-3 rounded-lg border p-3">
       <div className="mb-2 flex items-center gap-2">
-        <Wrench className="h-4 w-4 text-blue-500" />
+        <Wrench className="text-info h-4 w-4" />
         <span className="text-foreground text-sm font-medium">
           Tool: {toolName}
         </span>
 
         {state === 'output-available' && (
-          <CheckCircle className="h-4 w-4 text-green-500" />
+          <CheckCircle className="text-success h-4 w-4" />
         )}
         {state === 'output-error' && (
-          <AlertCircle className="h-4 w-4 text-red-500" />
+          <AlertCircle className="text-destructive h-4 w-4" />
         )}
         {state === 'input-streaming' && (
           <div className="flex items-center gap-1">
             <div
-              className="h-3 w-3 animate-spin rounded-full border
-                border-blue-500 border-t-transparent"
+              className="border-info h-3 w-3 animate-spin rounded-full border
+                border-t-transparent"
             />
             <span className="text-muted-foreground text-xs">Streaming...</span>
           </div>
@@ -136,7 +136,7 @@ function ToolCallComponentImpl({
             )}
             <span>Input Parameters</span>
             {state === 'input-streaming' && (
-              <span className="text-blue-500">(Streaming...)</span>
+              <span className="text-info">(Streaming...)</span>
             )}
           </button>
           {isInputOpen && (
@@ -165,7 +165,7 @@ function ToolCallComponentImpl({
               <ChevronRight className="h-3 w-3" />
             )}
             <span>Tool Result</span>
-            <CheckCircle className="h-3 w-3 text-green-500" />
+            <CheckCircle className="text-success h-3 w-3" />
           </button>
           {isOutputOpen && (
             <div className="mt-2">
@@ -177,17 +177,14 @@ function ToolCallComponentImpl({
 
       {state === 'output-error' && (
         <div
-          className="mt-2 rounded border border-red-200 bg-red-50 p-2
-            dark:border-red-800 dark:bg-red-950/20"
+          className="border-destructive/20 bg-destructive/10 mt-2 rounded border
+            p-2"
         >
-          <div
-            className="flex items-center gap-2 text-sm text-red-600
-              dark:text-red-400"
-          >
+          <div className="text-destructive flex items-center gap-2 text-sm">
             <AlertCircle className="h-4 w-4" />
             <strong>Tool Execution Error</strong>
           </div>
-          <div className="mt-1 text-xs text-red-700 dark:text-red-300">
+          <div className="text-destructive mt-1 text-xs">
             {'errorText' in part ? part.errorText : 'Tool execution failed'}
           </div>
         </div>
@@ -206,17 +203,13 @@ function ToolCallComponentImpl({
             part.input !== undefined &&
             'output' in part &&
             part.output !== undefined && (
-              <span className="text-green-600 dark:text-green-400">
-                ✓ Completed
-              </span>
+              <span className="text-success">✓ Completed</span>
             )}
           {state === 'input-streaming' && (
-            <span className="text-blue-600 dark:text-blue-400">
-              ⏳ Processing...
-            </span>
+            <span className="text-info">⏳ Processing...</span>
           )}
           {state === 'output-error' && (
-            <span className="text-red-600 dark:text-red-400">✗ Failed</span>
+            <span className="text-destructive">✗ Failed</span>
           )}
         </div>
       </div>
diff --git a/renderer/src/features/chat/components/dialog-provider-settings.tsx b/renderer/src/features/chat/components/dialog-provider-settings.tsx
index 1618572fb..b8eba981b 100644
--- a/renderer/src/features/chat/components/dialog-provider-settings.tsx
+++ b/renderer/src/features/chat/components/dialog-provider-settings.tsx
@@ -459,15 +459,15 @@ export function DialogProviderSettings({
                               <div
                                 className={`rounded-md border p-3 ${
                                   validationStatus[pk.provider.id]?.valid
-                                    ? 'border-green-500/20 bg-green-500/10'
-                                    : 'border-red-500/20 bg-red-500/10'
+                                    ? 'border-success/20 bg-success/10'
+                                    : 'border-destructive/20 bg-destructive/10'
                                 }`}
                               >
                                 <p
                                   className={`text-sm ${
                                     validationStatus[pk.provider.id]?.valid
-                                      ? 'text-green-600 dark:text-green-500'
-                                      : 'text-red-600 dark:text-red-500'
+                                      ? 'text-success'
+                                      : 'text-destructive'
                                   }`}
                                 >
                                   {validationStatus[pk.provider.id]?.valid
@@ -482,8 +482,8 @@ export function DialogProviderSettings({
                               (isLocalServerProvider(pk)
                                 ? pk.endpointURL.trim() !== ''
                                 : true) && (
-                                <div className="rounded-md border border-yellow-500/20 bg-yellow-500/10 p-3">
-                                  <p className="text-sm text-yellow-600 dark:text-yellow-500">
+                                <div className="border-warning/20 bg-warning/10 rounded-md border p-3">
+                                  <p className="text-warning text-sm">
                                     {pk.provider.id === 'ollama' ||
                                     pk.provider.id === 'lmstudio'
                                       ? `${pk.provider.name} server is not running or no models are installed. Please start ${pk.provider.name} and ensure you have models available, then click the refresh button above.`
diff --git a/renderer/src/features/chat/components/error-alert.tsx b/renderer/src/features/chat/components/error-alert.tsx
index 4c74902c8..a1dd0f153 100644
--- a/renderer/src/features/chat/components/error-alert.tsx
+++ b/renderer/src/features/chat/components/error-alert.tsx
@@ -34,8 +34,8 @@ export function ErrorAlert({ error, className = '' }: ErrorAlertProps) {
         <AlertDescription className="pr-8">
           <Separator className="my-2 flex-wrap" />
           <p
-            className="max-h-20 max-w-full overflow-auto font-mono text-xs
-              text-gray-300"
+            className="text-muted-foreground max-h-20 max-w-full overflow-auto
+              font-mono text-xs"
           >
             {error}
           </p>
diff --git a/renderer/src/features/chat/components/mcp-tools-modal.tsx b/renderer/src/features/chat/components/mcp-tools-modal.tsx
index 0ca910fbd..e17638be6 100644
--- a/renderer/src/features/chat/components/mcp-tools-modal.tsx
+++ b/renderer/src/features/chat/components/mcp-tools-modal.tsx
@@ -246,7 +246,7 @@ export function McpToolsModal({
                     >
                       <div className="min-w-0 flex-1">
                         <div className="mb-2 flex items-center gap-2">
-                          <Wrench className="h-4 w-4 text-blue-500" />
+                          <Wrench className="text-info h-4 w-4" />
                           <h4 className="text-sm font-medium">{tool.name}</h4>
                         </div>
 
diff --git a/renderer/src/features/chat/components/tool-results/skill-build-result-card.tsx b/renderer/src/features/chat/components/tool-results/skill-build-result-card.tsx
index 63395ae26..705d32d52 100644
--- a/renderer/src/features/chat/components/tool-results/skill-build-result-card.tsx
+++ b/renderer/src/features/chat/components/tool-results/skill-build-result-card.tsx
@@ -112,17 +112,16 @@ export function SkillBuildResultCard({ result }: { result: SkillBuildResult }) {
   return (
     <>
       <div
-        className="my-3 overflow-hidden rounded-xl border border-emerald-500/25
-          bg-linear-to-br from-emerald-500/5 via-transparent to-transparent
+        className="border-success/25 from-success/5 my-3 overflow-hidden
+          rounded-xl border bg-linear-to-br via-transparent to-transparent
           shadow-sm"
         data-testid="skill-build-result-card"
       >
         <div className="flex flex-col gap-4 p-4">
           <div className="flex items-start gap-3">
             <div
-              className="flex size-11 shrink-0 items-center justify-center
-                rounded-xl bg-emerald-500/15 text-emerald-600
-                dark:text-emerald-400"
+              className="bg-success/15 text-success flex size-11 shrink-0
+                items-center justify-center rounded-xl"
             >
               <PackageIcon className="size-5" />
             </div>
@@ -131,7 +130,7 @@ export function SkillBuildResultCard({ result }: { result: SkillBuildResult }) {
                 className="text-muted-foreground flex items-center gap-1.5
                   text-xs font-medium tracking-wide uppercase"
               >
-                <CheckCircle2Icon className="size-3.5 text-emerald-500" />
+                <CheckCircle2Icon className="text-success size-3.5" />
                 Skill built
               </div>
               <h4
diff --git a/renderer/src/features/mcp-servers/components/customize-tools-table.tsx b/renderer/src/features/mcp-servers/components/customize-tools-table.tsx
index 741359d00..89bcbdda8 100644
--- a/renderer/src/features/mcp-servers/components/customize-tools-table.tsx
+++ b/renderer/src/features/mcp-servers/components/customize-tools-table.tsx
@@ -204,7 +204,7 @@ export function CustomizeToolsTable({
                                 toolsOverride,
                                 overrideTools
                               )
-                                ? 'text-orange-500'
+                                ? 'text-warning'
                                 : 'text-primary'
                               }`}
                           />
@@ -285,7 +285,7 @@ export function CustomizeToolsTable({
 
     return (
       <Alert>
-        <TriangleAlert className="size-4 stroke-orange-500" />
+        <TriangleAlert className="stroke-warning size-4" />
         <AlertTitle className="flex items-center justify-between">
           <b>{alertConfig.title}</b>
         </AlertTitle>
diff --git a/renderer/src/features/mcp-servers/components/table-mcp-servers.tsx b/renderer/src/features/mcp-servers/components/table-mcp-servers.tsx
index 73604b4cb..458b6e60b 100644
--- a/renderer/src/features/mcp-servers/components/table-mcp-servers.tsx
+++ b/renderer/src/features/mcp-servers/components/table-mcp-servers.tsx
@@ -65,7 +65,7 @@ function UpdateVersionButton({
           disabled={disabled || !isReady}
           aria-label={`Update to ${drift.registryTag}`}
         >
-          <ArrowUpCircle className="size-5 text-amber-500" />
+          <ArrowUpCircle className="text-warning size-5" />
         </Button>
       </TooltipTrigger>
       <TooltipContent className="max-w-xs">
diff --git a/renderer/src/features/mcp-servers/sub-pages/logs-page/index.tsx b/renderer/src/features/mcp-servers/sub-pages/logs-page/index.tsx
index 7ac463ddf..24aba12ea 100644
--- a/renderer/src/features/mcp-servers/sub-pages/logs-page/index.tsx
+++ b/renderer/src/features/mcp-servers/sub-pages/logs-page/index.tsx
@@ -97,8 +97,8 @@ export function LogsPage() {
         </div>
       </div>
       <div
-        className="dark:border-secondary dark:bg-card max-h-[70vh] min-h-0
-          flex-1 overflow-auto rounded-md border bg-white"
+        className="bg-card dark:border-secondary max-h-[70vh] min-h-0 flex-1
+          overflow-auto rounded-md border"
       >
         {isLoadingState ? (
           <SkeletonLogs />
diff --git a/renderer/src/features/skills/components/build-detail-page.tsx b/renderer/src/features/skills/components/build-detail-page.tsx
index 7b8b130bb..8676b1628 100644
--- a/renderer/src/features/skills/components/build-detail-page.tsx
+++ b/renderer/src/features/skills/components/build-detail-page.tsx
@@ -129,7 +129,7 @@ export function BuildDetailPage({ build }: BuildDetailPageProps) {
               SKILL.md
             </h4>
             <div
-              className="border-border mb-8 rounded-2xl border bg-white p-6
+              className="border-border bg-card mb-8 rounded-2xl border p-6
                 dark:bg-transparent"
             >
               {tag ? (
diff --git a/renderer/src/features/skills/components/skill-detail-page.tsx b/renderer/src/features/skills/components/skill-detail-page.tsx
index c555318de..027b58e1d 100644
--- a/renderer/src/features/skills/components/skill-detail-page.tsx
+++ b/renderer/src/features/skills/components/skill-detail-page.tsx
@@ -164,7 +164,7 @@ export function SkillDetailPage({
               SKILL.md
             </h4>
             <div
-              className="border-border mb-8 rounded-2xl border bg-white p-6
+              className="border-border bg-card mb-8 rounded-2xl border p-6
                 dark:bg-transparent"
             >
               {ociRef ? (

From 2206bce31e624e050353ba62fef9b871efcd4302 Mon Sep 17 00:00:00 2001
From: Daniel Kantor <kd@stacklok.com>
Date: Tue, 19 May 2026 11:20:13 +0200
Subject: [PATCH 3/6] readme update

---
 branding-examples/README.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/branding-examples/README.md b/branding-examples/README.md
index a690fd671..e526198ed 100644
--- a/branding-examples/README.md
+++ b/branding-examples/README.md
@@ -1,8 +1,12 @@
 # Branding examples
 
-JSON files matching the `BrandingConfig` schema (`common/branding/schema.ts`). Point `BRANDING_CONFIG_PATH` at one and launch — they replace the default Stacklok palette without touching code.
+JSON files matching the `BrandingConfig` schema (`common/branding/schema.ts`).
+Point `BRANDING_CONFIG_PATH` at one and launch — they replace the default
+Stacklok palette without touching code.
 
-- `test-theme.json` — wine / coral / gold palette, deliberately distinct from studio's defaults. Used by `pnpm run start:customTheme` to stress-test that every themeable surface is wired to the override.
+- `test-theme.json` — wine / coral / gold palette, deliberately distinct from
+  studio's defaults. Used by `pnpm run start:customTheme` to stress-test that
+  every themeable surface is wired to the override.
 
 To use any of these on a normal launch, copy to `<userData>/branding-0.json`:
 
@@ -21,4 +25,8 @@ BRANDING_CONFIG_PATH="$PWD/branding-examples/test-theme.json" pnpm run start
 
 ## Schema
 
-See `common/branding/schema.ts`. Values must be complete CSS colors (`#hex`, `hsl(...)`, `oklch(...)`, `oklab(...)`, `rgb(...)`, `lab(...)`, `lch(...)`, `color(...)`, or CSS named colors). Bare HSL triplets like `0 60% 20%` are **not** supported — studio consumes vars as bare `var(--X)`, which needs a complete `<color>` value.
+See `common/branding/schema.ts`. Values must be complete CSS colors (`#hex`,
+`hsl(...)`, `oklch(...)`, `oklab(...)`, `rgb(...)`, `lab(...)`, `lch(...)`,
+`color(...)`, or CSS named colors). Bare HSL triplets like `0 60% 20%` are
+**not** supported — studio consumes vars as bare `var(--X)`, which needs a
+complete `<color>` value.

From 719b0561547eba47e166280938ffc5e261a98fd9 Mon Sep 17 00:00:00 2001
From: Daniel Kantor <kd@stacklok.com>
Date: Tue, 19 May 2026 14:11:25 +0200
Subject: [PATCH 4/6] fixes from review

---
 branding-examples/README.md                   |  6 ++
 branding-examples/cloud-ui.json               | 79 +++++++++++++++++++
 .../branding/__tests__/color-tokens.test.ts   |  6 +-
 common/branding/color-tokens.ts               | 52 +++++-------
 common/branding/schema.ts                     | 16 ++--
 main/src/branding/load.ts                     | 50 ++++++------
 main/src/branding/paths.ts                    | 14 +---
 main/src/main-window.ts                       |  7 +-
 preload/src/api/branding.ts                   | 25 ++----
 .../src/common/components/ui/textarea.tsx     |  9 +--
 renderer/src/renderer.tsx                     |  8 +-
 scripts/start-custom-theme.ts                 | 15 ++--
 12 files changed, 166 insertions(+), 121 deletions(-)
 create mode 100644 branding-examples/cloud-ui.json

diff --git a/branding-examples/README.md b/branding-examples/README.md
index e526198ed..945da3490 100644
--- a/branding-examples/README.md
+++ b/branding-examples/README.md
@@ -7,6 +7,10 @@ Stacklok palette without touching code.
 - `test-theme.json` — wine / coral / gold palette, deliberately distinct from
   studio's defaults. Used by `pnpm run start:customTheme` to stress-test that
   every themeable surface is wired to the override.
+- `cloud-ui.json` — Port of `toolhive-cloud-ui`'s default palette (zinc primary,
+  dark-green nav, green success / accent). Bare HSL triplets from the source are
+  wrapped in `hsl(…)` so they resolve in studio's bare-`var` consumers. Useful
+  for previewing what studio looks like when aligned with the cloud surface.
 
 To use any of these on a normal launch, copy to `<userData>/branding-0.json`:
 
@@ -21,6 +25,8 @@ Or override the path entirely:
 
 ```bash
 BRANDING_CONFIG_PATH="$PWD/branding-examples/test-theme.json" pnpm run start
+# or to test the cloud-ui-aligned palette:
+BRANDING_CONFIG_PATH="$PWD/branding-examples/cloud-ui.json" pnpm run start
 ```
 
 ## Schema
diff --git a/branding-examples/cloud-ui.json b/branding-examples/cloud-ui.json
new file mode 100644
index 000000000..ec0812d17
--- /dev/null
+++ b/branding-examples/cloud-ui.json
@@ -0,0 +1,79 @@
+{
+  "app_name": "ToolHive (cloud-ui palette)",
+  "design_tokens": {
+    "colors": {
+      "light": {
+        "background": "hsl(0 0% 100%)",
+        "foreground": "hsl(240 10% 3.9%)",
+        "card": "hsl(0 0% 100%)",
+        "card-foreground": "hsl(240 10% 3.9%)",
+        "popover": "hsl(0 0% 100%)",
+        "popover-foreground": "hsl(240 10% 3.9%)",
+        "primary": "hsl(240 5.9% 10%)",
+        "primary-foreground": "hsl(0 0% 98%)",
+        "secondary": "hsl(240 4.8% 95.9%)",
+        "secondary-foreground": "hsl(240 5.9% 10%)",
+        "muted": "hsl(240 4.8% 95.9%)",
+        "muted-foreground": "hsl(240 3.8% 46.1%)",
+        "accent": "hsl(140 30% 95%)",
+        "accent-foreground": "hsl(150 20% 15%)",
+        "destructive": "hsl(0 84.2% 60.2%)",
+        "destructive-foreground": "hsl(0 0% 98%)",
+        "border": "hsl(240 5.9% 90%)",
+        "input": "hsl(240 5.9% 90%)",
+        "ring": "hsl(240 5.9% 10%)",
+        "avatar-background": "oklch(0.696 0 0 / 89.8%)",
+        "nav-background": "#18442e",
+        "nav-border": "#265b41",
+        "nav-button-active-bg": "#398560",
+        "nav-button-active-text": "#ffffff",
+        "success": "oklch(0.5849 0.095 159.91)",
+        "warning": "oklch(0.769 0.158 70.08)",
+        "sidebar": "hsl(40 20% 98.5%)",
+        "sidebar-foreground": "hsl(240 5.3% 26.1%)",
+        "sidebar-primary": "hsl(240 5.9% 10%)",
+        "sidebar-primary-foreground": "hsl(0 0% 98%)",
+        "sidebar-accent": "hsl(240 4.8% 95.9%)",
+        "sidebar-accent-foreground": "hsl(240 5.9% 10%)",
+        "sidebar-border": "hsl(220 13% 91%)",
+        "sidebar-ring": "hsl(217.2 91.2% 59.8%)"
+      },
+      "dark": {
+        "background": "hsl(0 0% 7.5%)",
+        "foreground": "hsl(0 0% 98%)",
+        "card": "hsl(240 10% 3.9%)",
+        "card-foreground": "hsl(0 0% 98%)",
+        "popover": "hsl(240 10% 3.9%)",
+        "popover-foreground": "hsl(0 0% 98%)",
+        "primary": "hsl(0 0% 98%)",
+        "primary-foreground": "hsl(240 5.9% 10%)",
+        "secondary": "hsl(240 3.7% 15.9%)",
+        "secondary-foreground": "hsl(0 0% 98%)",
+        "muted": "hsl(240 3.7% 15.9%)",
+        "muted-foreground": "hsl(240 5% 64.9%)",
+        "accent": "hsl(150 40% 14%)",
+        "accent-foreground": "hsl(0 0% 98%)",
+        "destructive": "hsl(0 62.8% 30.6%)",
+        "destructive-foreground": "hsl(0 0% 98%)",
+        "border": "hsl(240 3.7% 15.9%)",
+        "input": "hsl(240 3.7% 15.9%)",
+        "ring": "hsl(240 4.9% 83.9%)",
+        "avatar-background": "oklch(0.696 0 0 / 89.8%)",
+        "nav-background": "#0f2e1e",
+        "nav-border": "#1a4430",
+        "nav-button-active-bg": "#2d6b4a",
+        "nav-button-active-text": "#f0f0f0",
+        "success": "oklch(0.724 0.1091 160.66)",
+        "warning": "oklch(0.828 0.159 70.13)",
+        "sidebar": "hsl(0 0% 7.5%)",
+        "sidebar-foreground": "hsl(240 4.8% 95.9%)",
+        "sidebar-primary": "hsl(224.3 76.3% 48%)",
+        "sidebar-primary-foreground": "hsl(0 0% 100%)",
+        "sidebar-accent": "hsl(240 3.7% 15.9%)",
+        "sidebar-accent-foreground": "hsl(240 4.8% 95.9%)",
+        "sidebar-border": "hsl(240 3.7% 15.9%)",
+        "sidebar-ring": "hsl(217.2 91.2% 59.8%)"
+      }
+    }
+  }
+}
diff --git a/common/branding/__tests__/color-tokens.test.ts b/common/branding/__tests__/color-tokens.test.ts
index 774fbedd2..7f69a691c 100644
--- a/common/branding/__tests__/color-tokens.test.ts
+++ b/common/branding/__tests__/color-tokens.test.ts
@@ -28,8 +28,6 @@ describe('tokensToCssDeclarations', () => {
   })
 
   it('drops unknown keys silently', () => {
-    // ColorTokens permits any string key on the wire; the runtime allowlist
-    // filters non-token keys before they're emitted as CSS variables.
     const out = tokensToCssDeclarations({
       'not-a-real-key': '#000',
       primary: '#fff',
@@ -60,8 +58,8 @@ describe('tokensToCssDeclarations', () => {
 })
 
 describe('colorTokensToStyleContent', () => {
-  it('returns an empty string when theme is null', () => {
-    expect(colorTokensToStyleContent(null)).toBe('')
+  it('returns an empty string when theme is undefined', () => {
+    expect(colorTokensToStyleContent(undefined)).toBe('')
   })
 
   it('returns an empty string when theme is empty', () => {
diff --git a/common/branding/color-tokens.ts b/common/branding/color-tokens.ts
index 4164c4240..913c98782 100644
--- a/common/branding/color-tokens.ts
+++ b/common/branding/color-tokens.ts
@@ -1,23 +1,17 @@
-// SEP#725 — brand color customization. Port of cloud-ui's `color-tokens.ts`
-// (see `sep/enterprise/toolhive-cloud-ui/src/lib/color-tokens.ts`).
-//
-// Override values are emitted into a `<style>` tag at runtime, so they reach
-// the browser as raw CSS. Values MUST be sanitized before emission to prevent
+// Brand-color override serialization. Values are emitted into a `<style>`
+// tag at runtime, so they MUST be sanitized before emission to prevent
 // stylesheet escape via `;`, `}`, comment markers, etc.
 
-// Per-mode color overrides from `BrandingConfig.design_tokens.colors`.
+export type ColorTokenMap = Record<string, string>
+
 export type ColorTokens = {
-  light?: { [key: string]: string }
-  dark?: { [key: string]: string }
+  light?: ColorTokenMap
+  dark?: ColorTokenMap
 }
 
-// Allowlist of CSS variable names that may be overridden. Mirrors cloud-ui's
-// list so a single `BrandingConfig` JSON is portable across both surfaces.
-// Studio's `renderer/src/index.css` declares all of these except
-// `avatar-background` and `destructive-foreground`; those two are silently
-// no-ops here until studio's CSS adds them, but stay in the allowlist so
-// configs authored for cloud-ui don't trip the unknown-key drop. The leading
-// `--` is added at serialization time.
+// Allowlist of CSS variable names that may be overridden. Keys not declared
+// in `renderer/src/index.css` are silent no-ops. The leading `--` is added
+// at serialization time.
 const COLOR_TOKEN_KEYS = [
   'background',
   'foreground',
@@ -63,14 +57,12 @@ type ColorTokenKey = (typeof COLOR_TOKEN_KEYS)[number]
 
 const COLOR_TOKEN_KEY_SET: ReadonlySet<string> = new Set(COLOR_TOKEN_KEYS)
 
-// Longest plausible CSS color value (e.g. `oklch(0.5849 0.095 159.91 / 100%)`)
-// is well under 50 chars; 100 is generous enough to absorb formatting variation
-// while still capping pathological input that could explode the `<style>` body.
+// Caps pathological input that could explode the `<style>` body. Real values
+// (e.g. `oklch(0.5849 0.095 159.91 / 100%)`) are well under 50 chars.
 const MAX_VALUE_LENGTH = 100
 
-// Reject any character or sequence that could close the property/declaration
-// or open a comment inside the emitted `<style>` block. `url(` is blocked as
-// defense-in-depth.
+// Reject anything that could close the property/declaration or open a comment
+// inside the emitted `<style>` block. `url(` blocked as defense-in-depth.
 const UNSAFE_VALUE_PATTERN = /[;{}<>\n\r\\]|\/\*|\*\/|url\(/i
 
 function isColorTokenKey(key: string): key is ColorTokenKey {
@@ -86,11 +78,10 @@ function isValidColorTokenValue(value: unknown): value is string {
   )
 }
 
-// Render one mode's color token map as a CSS declaration list (no surrounding
-// selector). Unknown keys and unsafe values are dropped silently — partial
-// output is preferable to no override at all.
+// Unknown keys and unsafe values are dropped silently — partial output is
+// preferable to no override at all.
 export function tokensToCssDeclarations(
-  tokens: ColorTokens['light'] | undefined
+  tokens: ColorTokenMap | undefined
 ): string {
   if (!tokens) return ''
   const parts: string[] = []
@@ -102,13 +93,12 @@ export function tokensToCssDeclarations(
   return parts.join(' ')
 }
 
-// Selector choice — `:root:not(.dark)` for light, `.dark` for dark — matches
-// cloud-ui. The `:not(.dark)` is load-bearing: a bare `:root` would tie with
-// `.dark` on specificity and leak light values into dark mode via source
-// order. `:root:not(.dark)` doesn't match in dark mode, so the cascade picks
-// up the default `.dark` declaration in `renderer/src/index.css`.
+// `:not(.dark)` is load-bearing: a bare `:root` would tie with `.dark` on
+// specificity and leak light values into dark mode via source order.
+// `:root:not(.dark)` doesn't match in dark mode, so the cascade picks up
+// the default `.dark` declaration in `renderer/src/index.css`.
 export function colorTokensToStyleContent(
-  tokens: ColorTokens | null | undefined
+  tokens: ColorTokens | undefined
 ): string {
   if (!tokens) return ''
   const lightDecls = tokensToCssDeclarations(tokens.light)
diff --git a/common/branding/schema.ts b/common/branding/schema.ts
index 7a1bca9c5..acc1e5b79 100644
--- a/common/branding/schema.ts
+++ b/common/branding/schema.ts
@@ -1,14 +1,8 @@
 import { z } from 'zod/v4'
 
-// SEP#725 — Shape of the JSON at the branding config path. Matches cloud-ui's
-// `BrandingConfig` (`sep/enterprise/toolhive-cloud-ui/src/lib/branding-config.ts`).
-// Field names are snake-cased so operators write idiomatic JSON. All fields
-// are optional; missing fields fall back to the bundled defaults.
-//
-// Studio currently consumes only `design_tokens.colors`; the non-color fields
-// (`app_name`, `logo_url`, `favicon_url`) are parsed for forward compatibility
-// but not yet applied — see the "Non-color fields" deferred decision in
-// scratchpad / SEP#725.
+// Shape of the JSON at the branding config path. Studio currently consumes
+// only `design_tokens.colors`; the other fields are parsed for forward
+// compatibility but not yet applied.
 
 const colorMap = z.record(z.string(), z.string())
 
@@ -28,8 +22,8 @@ export const brandingConfigSchema = z
       })
       .optional(),
   })
-  // Reject unknown top-level keys silently rather than failing — operators
-  // may pass through extra fields the config server adds in the future.
+  // Tolerate unknown top-level keys — operators may pass through extra fields
+  // the config server adds in the future.
   .loose()
 
 export type BrandingConfig = z.infer<typeof brandingConfigSchema>
diff --git a/main/src/branding/load.ts b/main/src/branding/load.ts
index 21d6dee38..4a6f25d6f 100644
--- a/main/src/branding/load.ts
+++ b/main/src/branding/load.ts
@@ -6,18 +6,14 @@ import {
 import { colorTokensToStyleContent } from '@common/branding/color-tokens'
 import log from '../logger'
 
-// SEP#725 — Load the operator-supplied branding config and serialize the
-// color-token overrides into a CSS string the renderer can inject verbatim
-// into a `<style>` tag.
-//
-// One-shot read at boot. To pick up edits to the JSON without an app
-// restart, replace this with an `fs.watch`-driven emitter that pushes
-// updates to the renderer over IPC — out of scope for the initial cut
-// (see scratchpad "Hot reload vs restart-required" decision).
-//
-// Returns `null` on any read / parse / shape error. All failure modes are
-// logged at warn level so a broken config surfaces in studio logs instead of
-// silently falling back to the default palette.
+// Load the operator-supplied branding config. One-shot read at boot;
+// restart required to pick up edits. Returns `null` on any read / parse /
+// shape error; failures are warn-logged so a broken config surfaces in logs
+// instead of silently falling back to the default palette.
+
+function isEnoent(err: unknown): err is NodeJS.ErrnoException {
+  return err instanceof Error && 'code' in err && err.code === 'ENOENT'
+}
 
 export async function loadBrandingConfig(
   filePath: string
@@ -27,13 +23,7 @@ export async function loadBrandingConfig(
     raw = await readFile(filePath, 'utf-8')
   } catch (err) {
     // ENOENT is the common "operator didn't configure anything" case — quiet.
-    if (
-      err instanceof Error &&
-      'code' in err &&
-      (err as NodeJS.ErrnoException).code === 'ENOENT'
-    ) {
-      return null
-    }
+    if (isEnoent(err)) return null
     log.warn(
       `[branding] failed to read ${filePath}: ${
         err instanceof Error ? err.message : String(err)
@@ -61,12 +51,28 @@ export async function loadBrandingConfig(
     )
     return null
   }
+
+  // Operator-typo trap: Zod's default `.strip()` silently drops unknown
+  // nested keys (e.g. `design_tokens.color` instead of `colors`). Warn-log
+  // so the operator sees their typo instead of a silent default-fallback.
+  if (parsed && typeof parsed === 'object' && 'design_tokens' in parsed) {
+    const dt = (parsed as { design_tokens?: unknown }).design_tokens
+    if (dt && typeof dt === 'object') {
+      for (const key of Object.keys(dt)) {
+        if (key !== 'colors') {
+          log.warn(
+            `[branding] ${filePath}: unknown design_tokens.${key} (did you mean "colors"?)`
+          )
+        }
+      }
+    }
+  }
+
   return result.data
 }
 
-// Composes the loader + the renderer-facing CSS emitter. Returns an empty
-// string if there is no config, or no color overrides in the config, so the
-// renderer can unconditionally inject the result into a `<style>` block.
+// Returns an empty string when there's no config or no color overrides, so
+// the renderer can unconditionally inject the result into a `<style>` block.
 export async function getBrandingCss(filePath: string): Promise<string> {
   const config = await loadBrandingConfig(filePath)
   return colorTokensToStyleContent(config?.design_tokens?.colors)
diff --git a/main/src/branding/paths.ts b/main/src/branding/paths.ts
index db4c3394a..fb4cdd5f7 100644
--- a/main/src/branding/paths.ts
+++ b/main/src/branding/paths.ts
@@ -1,17 +1,9 @@
 import path from 'node:path'
 import { app } from 'electron'
 
-// SEP#725 — Resolve the branding config file path.
-//
-// Single override file. Env-var override matches cloud-ui's `BRANDING_CONFIG_PATH`
-// for muscle memory. Default: `<userData>/branding-0.json` — per-OS-correct
-// via Electron (`~/Library/Application Support/...` on macOS, `%APPDATA%/...`
-// on Windows, `~/.config/...` on Linux).
-//
-// The `-0` suffix is future-proofing: layered `branding-N.json` precedence
-// (highest N wins, per the Slack design in thread 1778080552.563009) is out
-// of scope for MVP, but reserving the naming slot now lets a future loader
-// add layering without renaming operator-deployed files.
+// Resolve the branding config file path. The `-0` suffix reserves the
+// naming slot for a potential future layered `branding-N.json` precedence
+// (out of scope here) without renaming operator-deployed files.
 
 const ENV_VAR = 'BRANDING_CONFIG_PATH'
 
diff --git a/main/src/main-window.ts b/main/src/main-window.ts
index f9fee3328..16deccdc2 100644
--- a/main/src/main-window.ts
+++ b/main/src/main-window.ts
@@ -157,10 +157,9 @@ export async function createMainWindow(
   try {
     log.info('Creating main window...')
 
-    // SEP#725 — load the operator-supplied branding CSS (if any) and pass it
-    // to the renderer via additionalArguments. Preload reads it from
-    // process.argv synchronously; renderer injects before React mounts so
-    // there's no FOUC. See preload/src/api/branding.ts.
+    // Pass the operator-supplied branding CSS (if any) to the renderer via
+    // additionalArguments; preload reads it synchronously so the renderer
+    // can inject before React mounts.
     const brandingCss = await getBrandingCss(getBrandingConfigPath())
     const brandingArg = `--branding-css=${Buffer.from(brandingCss, 'utf-8').toString('base64')}`
 
diff --git a/preload/src/api/branding.ts b/preload/src/api/branding.ts
index b4128c285..68e188448 100644
--- a/preload/src/api/branding.ts
+++ b/preload/src/api/branding.ts
@@ -1,16 +1,8 @@
-// SEP#725 — Brand color overrides.
-//
-// Main process reads the operator's `branding-0.json`, serializes it to a CSS
-// string, and passes it to the renderer process via `webPreferences.additional
-// Arguments`. Preload picks it out of `process.argv`, decodes it, and exposes
-// it as a string constant on `electronAPI.branding.css`. The renderer injects
-// it into `<head>` synchronously before mounting React — no IPC roundtrip,
-// no FOUC.
-//
-// Argument format: `--branding-css=<base64-encoded-utf-8>`. Base64 keeps the
-// CSS opaque to shell / argv quoting concerns; an empty CSS string is encoded
-// as the empty payload. If the arg isn't present (e.g. tests, a window not
-// created by `createMainWindow`), we expose an empty string.
+// Pick the branding CSS out of `process.argv` (set by the main process via
+// `webPreferences.additionalArguments`) and expose it on `electronAPI.branding.css`.
+// Synchronous read avoids an IPC roundtrip and a flash of unstyled content.
+// Argument format: `--branding-css=<base64-encoded-utf-8>` — base64 keeps the
+// CSS opaque to shell / argv quoting.
 
 const ARG_PREFIX = '--branding-css='
 
@@ -19,11 +11,8 @@ function readBrandingCss(): string {
   if (!arg) return ''
   const encoded = arg.slice(ARG_PREFIX.length)
   if (!encoded) return ''
-  try {
-    return Buffer.from(encoded, 'base64').toString('utf-8')
-  } catch {
-    return ''
-  }
+  // Buffer.from(..., 'base64') silently drops invalid bytes — never throws.
+  return Buffer.from(encoded, 'base64').toString('utf-8')
 }
 
 export const brandingApi = {
diff --git a/renderer/src/common/components/ui/textarea.tsx b/renderer/src/common/components/ui/textarea.tsx
index 94a899319..76d9d29ec 100644
--- a/renderer/src/common/components/ui/textarea.tsx
+++ b/renderer/src/common/components/ui/textarea.tsx
@@ -10,11 +10,10 @@ function Textarea({ className, ...props }: React.ComponentProps<'textarea'>) {
         `border-input placeholder:text-muted-foreground
         focus-visible:border-ring focus-visible:ring-ring/50
         aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40
-        aria-invalid:border-destructive bg-input dark:bg-card flex
-        field-sizing-content min-h-16 w-full rounded-md border px-3 py-2
-        text-base shadow-xs transition-[color,box-shadow] outline-none
-        focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50
-        md:text-sm`,
+        aria-invalid:border-destructive bg-card flex field-sizing-content
+        min-h-16 w-full rounded-md border px-3 py-2 text-base shadow-xs
+        transition-[color,box-shadow] outline-none focus-visible:ring-[3px]
+        disabled:cursor-not-allowed disabled:opacity-50 md:text-sm`,
         className
       )}
       {...props}
diff --git a/renderer/src/renderer.tsx b/renderer/src/renderer.tsx
index 28bdfda0b..375c03472 100644
--- a/renderer/src/renderer.tsx
+++ b/renderer/src/renderer.tsx
@@ -18,12 +18,8 @@ import './common/lib/feature-flags'
 // Import OS design devtools to bind OsDesign.setMac/setWindows/reset to window
 import './common/lib/os-design'
 
-// SEP#725 — Apply operator-supplied brand color overrides before mounting
-// React, so the first paint shows the branded palette and there's no FOUC.
-// The CSS is computed in the main process from `branding-0.json` and forwarded
-// to preload via webPreferences.additionalArguments. See:
-//   - main/src/main-window.ts (load + pass)
-//   - preload/src/api/branding.ts (decode + expose)
+// Inject brand color overrides before mounting React so the first paint
+// shows the branded palette (no FOUC). CSS is sourced from the main process.
 const brandingCss = window.electronAPI?.branding?.css
 if (brandingCss) {
   const styleEl = document.createElement('style')
diff --git a/scripts/start-custom-theme.ts b/scripts/start-custom-theme.ts
index b22253335..2e6870630 100644
--- a/scripts/start-custom-theme.ts
+++ b/scripts/start-custom-theme.ts
@@ -1,11 +1,9 @@
 #!/usr/bin/env tsx
 /**
- * Dev helper: launch the app with the test theme at
- * `branding-examples/test-theme.json` so we can verify that every themeable
- * surface in studio is actually wired to the branding override. The theme
- * uses a deliberately-distinct wine/coral/gold palette unmistakable from
- * studio's defaults. Cross-platform env-var setting (vs. inline `KEY=val` in
- * package.json, which breaks on Windows cmd.exe).
+ * Dev helper: launch the app with `branding-examples/test-theme.json` to
+ * verify every themeable surface is wired to the branding override. Uses a
+ * tsx wrapper instead of inline `KEY=val` in package.json (which breaks on
+ * Windows cmd.exe).
  */
 import { spawn } from 'node:child_process'
 import path from 'node:path'
@@ -26,9 +24,8 @@ const child = spawn('pnpm', ['exec', 'electron-forge', 'start'], {
   },
 })
 
-child.on('exit', (code, signal) => {
-  if (signal) process.kill(process.pid, signal)
-  else process.exit(code ?? 0)
+child.on('exit', (code) => {
+  process.exit(code ?? 1)
 })
 
 for (const sig of ['SIGINT', 'SIGTERM'] as const) {

From 43f331fe937cd60beb2876a1580c993a54cec354 Mon Sep 17 00:00:00 2001
From: Daniel Kantor <kd@stacklok.com>
Date: Tue, 19 May 2026 14:25:47 +0200
Subject: [PATCH 5/6] address more review feedback

---
 common/branding/color-tokens.ts | 26 +++++++++++++++++++++-----
 common/branding/schema.ts       |  2 +-
 2 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/common/branding/color-tokens.ts b/common/branding/color-tokens.ts
index 913c98782..5931f66f2 100644
--- a/common/branding/color-tokens.ts
+++ b/common/branding/color-tokens.ts
@@ -2,7 +2,10 @@
 // tag at runtime, so they MUST be sanitized before emission to prevent
 // stylesheet escape via `;`, `}`, comment markers, etc.
 
-export type ColorTokenMap = Record<string, string>
+// Values arrive as `unknown` because the schema deliberately doesn't constrain
+// them — see `schema.ts`. Per-value validation happens in
+// `isValidColorTokenValue` below.
+export type ColorTokenMap = Record<string, unknown>
 
 export type ColorTokens = {
   light?: ColorTokenMap
@@ -78,16 +81,29 @@ function isValidColorTokenValue(value: unknown): value is string {
   )
 }
 
-// Unknown keys and unsafe values are dropped silently — partial output is
-// preferable to no override at all.
+// Unknown keys and unsafe values are dropped per-entry — partial output is
+// preferable to no override at all. Each drop is warn-logged so a malformed
+// override doesn't silently revert to default.
 export function tokensToCssDeclarations(
   tokens: ColorTokenMap | undefined
 ): string {
   if (!tokens) return ''
   const parts: string[] = []
   for (const [key, value] of Object.entries(tokens)) {
-    if (!isColorTokenKey(key)) continue
-    if (!isValidColorTokenValue(value)) continue
+    if (!isColorTokenKey(key)) {
+      console.warn(
+        `[branding] dropping unknown token "${key}" ` +
+          `(not in the ${COLOR_TOKEN_KEYS.length}-key allowlist)`
+      )
+      continue
+    }
+    if (!isValidColorTokenValue(value)) {
+      console.warn(
+        `[branding] dropping unsafe value for "${key}" ` +
+          `(must be a non-empty string ≤${MAX_VALUE_LENGTH} chars without ;{}<>/\\ etc.)`
+      )
+      continue
+    }
     parts.push(`--${key}: ${value};`)
   }
   return parts.join(' ')
diff --git a/common/branding/schema.ts b/common/branding/schema.ts
index acc1e5b79..c3b3b5e55 100644
--- a/common/branding/schema.ts
+++ b/common/branding/schema.ts
@@ -4,7 +4,7 @@ import { z } from 'zod/v4'
 // only `design_tokens.colors`; the other fields are parsed for forward
 // compatibility but not yet applied.
 
-const colorMap = z.record(z.string(), z.string())
+const colorMap = z.record(z.string(), z.unknown())
 
 export const brandingConfigSchema = z
   .object({

From 60b8fb62b67cb0e5e968eb43c8624a468e49dc76 Mon Sep 17 00:00:00 2001
From: Daniel Kantor <kd@stacklok.com>
Date: Tue, 19 May 2026 14:37:22 +0200
Subject: [PATCH 6/6] test fixes

---
 .../branding/__tests__/color-tokens.test.ts   | 26 +++++++++++++++++--
 main/src/branding/__tests__/load.test.ts      | 20 +++++++++++---
 2 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/common/branding/__tests__/color-tokens.test.ts b/common/branding/__tests__/color-tokens.test.ts
index 7f69a691c..b158d03e2 100644
--- a/common/branding/__tests__/color-tokens.test.ts
+++ b/common/branding/__tests__/color-tokens.test.ts
@@ -1,9 +1,19 @@
-import { describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import {
   colorTokensToStyleContent,
   tokensToCssDeclarations,
 } from '@common/branding/color-tokens'
 
+let warnSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  warnSpy.mockRestore()
+})
+
 describe('tokensToCssDeclarations', () => {
   it('returns an empty string for undefined', () => {
     expect(tokensToCssDeclarations(undefined)).toBe('')
@@ -27,12 +37,15 @@ describe('tokensToCssDeclarations', () => {
     expect(out).toBe('--primary: #ff6600; --secondary: #0066ff;')
   })
 
-  it('drops unknown keys silently', () => {
+  it('drops unknown keys with a warn-log', () => {
     const out = tokensToCssDeclarations({
       'not-a-real-key': '#000',
       primary: '#fff',
     })
     expect(out).toBe('--primary: #fff;')
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('unknown token "not-a-real-key"')
+    )
   })
 
   it.each([
@@ -45,6 +58,15 @@ describe('tokensToCssDeclarations', () => {
     ['over-length', 'a'.repeat(101)],
   ])('drops values rejected by the safety check (%s)', (_label, badValue) => {
     expect(tokensToCssDeclarations({ primary: badValue })).toBe('')
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('unsafe value for "primary"')
+    )
+  })
+
+  it('drops non-string values (numbers, null) with a warn-log', () => {
+    const out = tokensToCssDeclarations({ primary: 123, secondary: null })
+    expect(out).toBe('')
+    expect(warnSpy).toHaveBeenCalledTimes(2)
   })
 
   it('accepts oklch and hsl values', () => {
diff --git a/main/src/branding/__tests__/load.test.ts b/main/src/branding/__tests__/load.test.ts
index e97f15e03..92aac0021 100644
--- a/main/src/branding/__tests__/load.test.ts
+++ b/main/src/branding/__tests__/load.test.ts
@@ -1,4 +1,12 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+
+let warnSpy: ReturnType<typeof vi.spyOn>
+beforeEach(() => {
+  warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+})
+afterEach(() => {
+  warnSpy.mockRestore()
+})
 
 const { mockReadFile } = vi.hoisted(() => ({ mockReadFile: vi.fn() }))
 
@@ -116,7 +124,7 @@ describe('getBrandingCss', () => {
     )
   })
 
-  it('drops unknown token keys silently', async () => {
+  it('drops unknown token keys with a warn-log', async () => {
     mockReadFile.mockResolvedValueOnce(
       JSON.stringify({
         design_tokens: {
@@ -129,9 +137,12 @@ describe('getBrandingCss', () => {
     await expect(getBrandingCss(FAKE_PATH)).resolves.toBe(
       ':root:not(.dark) { --primary: #abc; }'
     )
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('unknown token "not-a-real-token"')
+    )
   })
 
-  it('drops values that fail sanitization', async () => {
+  it('drops values that fail sanitization with a warn-log', async () => {
     mockReadFile.mockResolvedValueOnce(
       JSON.stringify({
         design_tokens: {
@@ -140,5 +151,8 @@ describe('getBrandingCss', () => {
       })
     )
     await expect(getBrandingCss(FAKE_PATH)).resolves.toBe('')
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('unsafe value for "primary"')
+    )
   })
 })