feat: implement CSS variable override system for tenant themes (#1395)

* feat: implement CSS variable override system for tenant themes

Adds theme-utils.ts with applyTenantTheme, resetTheme, and updateFavicon
functions. Integrates into TenantProvider via useEffect so theme is applied
on tenant config change and cleaned up on unmount or tenant switch.

* fix: clear stale theme properties on switch, reset only on unmount

applyTenantTheme now removes previously applied CSS variables before setting
new ones, preventing stale properties when switching between themes with
different property sets. TenantProvider cleanup now runs resetTheme only on
unmount to avoid a visual flash during theme switches.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

frontend/src/contexts/tenant-context.tsx

@@ -1,7 +1,8 @@
-import { createContext, useContext, useState, useCallback, type ReactNode } from 'react'
+import { createContext, useContext, useState, useCallback, useEffect, type ReactNode } from 'react'
 import { useQueryClient } from '@tanstack/react-query'
 import { useAuth } from '@/contexts/auth-context'
-import { DEFAULT_UI_CONFIG, type TenantUIConfig } from '@/lib/tenant-ui-config'
+import { DEFAULT_UI_CONFIG, type TenantThemeConfig, type TenantUIConfig } from '@/lib/tenant-ui-config'
+import { applyTenantTheme, resetTheme } from '@/lib/theme-utils'
 
 export interface Tenant {
   id: string
@@ -15,6 +16,7 @@ export interface TenantContextValue {
   isPlatformAdmin: boolean
   switchTenant: (tenant: Tenant) => void
   clearTenant: () => void
+  applyTheme: (theme: TenantThemeConfig) => void
   tenantConfig?: TenantUIConfig
 }
 
@@ -24,9 +26,23 @@ export function TenantProvider({ children }: { children: ReactNode }) {
   const { claims, lens } = useAuth()
   const queryClient = useQueryClient()
   const [selectedTenant, setSelectedTenant] = useState<Tenant | null>(null)
+  const [tenantTheme, setTenantTheme] = useState<TenantThemeConfig | null>(null)
 
   const isPlatformAdmin = lens === 'platform'
 
+  useEffect(() => {
+    if (tenantTheme) {
+      applyTenantTheme(tenantTheme)
+    } else {
+      resetTheme()
+    }
+  }, [tenantTheme])
+
+  // Reset theme only on unmount to avoid a visual flash during theme switches.
+  useEffect(() => {
+    return () => resetTheme()
+  }, [])
+
   const switchTenant = useCallback(
     (tenant: Tenant) => {
       if (!isPlatformAdmin) return
@@ -50,8 +66,13 @@ export function TenantProvider({ children }: { children: ReactNode }) {
   const clearTenant = useCallback(() => {
     if (!isPlatformAdmin) return
     setSelectedTenant(null)
+    setTenantTheme(null)
   }, [isPlatformAdmin])
 
+  const applyTheme = useCallback((theme: TenantThemeConfig) => {
+    setTenantTheme(theme)
+  }, [])
+
   // For tenant admins, tenant slug is fixed from JWT claims
   const tenantSlug = isPlatformAdmin ? selectedTenant?.slug ?? null : claims?.tenantId ?? null
 
@@ -61,6 +82,7 @@ export function TenantProvider({ children }: { children: ReactNode }) {
     isPlatformAdmin,
     switchTenant,
     clearTenant,
+    applyTheme,
     tenantConfig: DEFAULT_UI_CONFIG,
   }
 

frontend/src/lib/__tests__/theme-utils.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import { applyTenantTheme, resetTheme, updateFavicon } from "../theme-utils"
+
+describe("theme-utils", () => {
+  beforeEach(() => {
+    // Clean slate for each test
+    document.documentElement.removeAttribute("data-tenant-theme")
+    document.documentElement.style.cssText = ""
+    // Remove any favicon links added during tests
+    document.querySelectorAll("link[rel~='icon']").forEach((el) => el.remove())
+  })
+
+  afterEach(() => {
+    resetTheme()
+  })
+
+  describe("applyTenantTheme", () => {
+    it("applies primaryColor as --primary CSS variable", () => {
+      applyTenantTheme({ primaryColor: "#007bff" })
+      expect(document.documentElement.style.getPropertyValue("--primary")).toBe("#007bff")
+    })
+
+    it("applies fontFamily as --font-family CSS variable", () => {
+      applyTenantTheme({ primaryColor: "#000", fontFamily: "Inter" })
+      expect(document.documentElement.style.getPropertyValue("--font-family")).toBe("Inter")
+    })
+
+    it("does not set --font-family when fontFamily is absent", () => {
+      applyTenantTheme({ primaryColor: "#000" })
+      expect(document.documentElement.style.getPropertyValue("--font-family")).toBe("")
+    })
+
+    it("records applied properties in data attribute", () => {
+      applyTenantTheme({ primaryColor: "#ff0000", fontFamily: "Roboto" })
+      const attr = document.documentElement.getAttribute("data-tenant-theme")
+      expect(attr).toContain("--primary")
+      expect(attr).toContain("--font-family")
+    })
+
+    it("sets favicon when faviconUrl is provided", () => {
+      applyTenantTheme({ primaryColor: "#000", faviconUrl: "https://example.com/favicon.ico" })
+      const link = document.querySelector<HTMLLinkElement>("link[rel~='icon']")
+      expect(link?.href).toBe("https://example.com/favicon.ico")
+    })
+
+    it("does not create favicon element when faviconUrl is absent", () => {
+      applyTenantTheme({ primaryColor: "#000" })
+      const link = document.querySelector("link[rel~='icon']")
+      expect(link).toBeNull()
+    })
+
+    it("overwrites a previous theme application", () => {
+      applyTenantTheme({ primaryColor: "#ff0000" })
+      applyTenantTheme({ primaryColor: "#00ff00" })
+      expect(document.documentElement.style.getPropertyValue("--primary")).toBe("#00ff00")
+    })
+
+    it("clears stale properties when switching to a theme with fewer properties", () => {
+      applyTenantTheme({ primaryColor: "#ff0000", fontFamily: "Inter" })
+      expect(document.documentElement.style.getPropertyValue("--font-family")).toBe("Inter")
+
+      // Switch to a theme without fontFamily — stale --font-family should be removed
+      applyTenantTheme({ primaryColor: "#00ff00" })
+      expect(document.documentElement.style.getPropertyValue("--primary")).toBe("#00ff00")
+      expect(document.documentElement.style.getPropertyValue("--font-family")).toBe("")
+    })
+  })
+
+  describe("resetTheme", () => {
+    it("removes --primary CSS variable", () => {
+      applyTenantTheme({ primaryColor: "#007bff" })
+      resetTheme()
+      expect(document.documentElement.style.getPropertyValue("--primary")).toBe("")
+    })
+
+    it("removes --font-family CSS variable", () => {
+      applyTenantTheme({ primaryColor: "#000", fontFamily: "Inter" })
+      resetTheme()
+      expect(document.documentElement.style.getPropertyValue("--font-family")).toBe("")
+    })
+
+    it("removes the data-tenant-theme attribute", () => {
+      applyTenantTheme({ primaryColor: "#007bff" })
+      resetTheme()
+      expect(document.documentElement.getAttribute("data-tenant-theme")).toBeNull()
+    })
+
+    it("is a no-op when no theme was applied", () => {
+      expect(() => resetTheme()).not.toThrow()
+      expect(document.documentElement.getAttribute("data-tenant-theme")).toBeNull()
+    })
+
+    it("restores the original favicon href", () => {
+      // Set up a starting favicon
+      const link = document.createElement("link")
+      link.rel = "icon"
+      link.href = "https://example.com/original.ico"
+      document.head.appendChild(link)
+
+      applyTenantTheme({ primaryColor: "#000", faviconUrl: "https://example.com/tenant.ico" })
+      expect(link.href).toBe("https://example.com/tenant.ico")
+
+      resetTheme()
+      expect(link.href).toBe("https://example.com/original.ico")
+    })
+  })
+
+  describe("updateFavicon", () => {
+    it("creates a favicon link element if none exists", () => {
+      updateFavicon("https://example.com/favicon.ico")
+      const link = document.querySelector<HTMLLinkElement>("link[rel~='icon']")
+      expect(link).not.toBeNull()
+      expect(link?.href).toBe("https://example.com/favicon.ico")
+    })
+
+    it("updates an existing favicon link element", () => {
+      const link = document.createElement("link")
+      link.rel = "icon"
+      link.href = "https://example.com/old.ico"
+      document.head.appendChild(link)
+
+      updateFavicon("https://example.com/new.ico")
+      expect(link.href).toBe("https://example.com/new.ico")
+    })
+
+    it("records the original href in data-default-href", () => {
+      const link = document.createElement("link")
+      link.rel = "icon"
+      link.href = "https://example.com/original.ico"
+      document.head.appendChild(link)
+
+      updateFavicon("https://example.com/new.ico")
+      expect(link.dataset.defaultHref).toBe("https://example.com/original.ico")
+    })
+
+    it("does not overwrite data-default-href on subsequent calls", () => {
+      const link = document.createElement("link")
+      link.rel = "icon"
+      link.href = "https://example.com/original.ico"
+      document.head.appendChild(link)
+
+      updateFavicon("https://example.com/first.ico")
+      updateFavicon("https://example.com/second.ico")
+
+      // defaultHref should still point to the original
+      expect(link.dataset.defaultHref).toBe("https://example.com/original.ico")
+      expect(link.href).toBe("https://example.com/second.ico")
+    })
+  })
+})

frontend/src/lib/theme-utils.ts

@@ -0,0 +1,93 @@
+import type { TenantThemeConfig } from "@/lib/tenant-ui-config"
+
+const TENANT_THEME_ATTR = "data-tenant-theme"
+
+// Maps TenantThemeConfig properties to CSS custom property names used by shadcn/ui
+const COLOR_PROPERTY_MAP: Record<string, string> = {
+  primaryColor: "--primary",
+  fontFamily: "--font-family",
+}
+
+/**
+ * Applies tenant theme CSS variables to the document root element.
+ * Marks overridden variables with a data attribute for cleanup.
+ */
+export function applyTenantTheme(theme: TenantThemeConfig): void {
+  const root = document.documentElement
+
+  // Clear any previously applied variables so stale properties don't linger
+  // when switching between themes that have different sets of properties.
+  const previouslyApplied = root.getAttribute(TENANT_THEME_ATTR)
+  if (previouslyApplied) {
+    for (const prop of previouslyApplied.split(",")) {
+      if (prop) {
+        root.style.removeProperty(prop)
+      }
+    }
+  }
+
+  const applied: string[] = []
+
+  if (theme.primaryColor) {
+    root.style.setProperty(COLOR_PROPERTY_MAP.primaryColor, theme.primaryColor)
+    applied.push(COLOR_PROPERTY_MAP.primaryColor)
+  }
+
+  if (theme.fontFamily) {
+    root.style.setProperty(COLOR_PROPERTY_MAP.fontFamily, theme.fontFamily)
+    applied.push(COLOR_PROPERTY_MAP.fontFamily)
+  }
+
+  // Record which variables were applied so resetTheme knows what to remove
+  root.setAttribute(TENANT_THEME_ATTR, applied.join(","))
+
+  if (theme.faviconUrl) {
+    updateFavicon(theme.faviconUrl)
+  }
+}
+
+/**
+ * Removes all CSS variable overrides applied by applyTenantTheme and
+ * restores the default favicon.
+ */
+export function resetTheme(): void {
+  const root = document.documentElement
+
+  const applied = root.getAttribute(TENANT_THEME_ATTR)
+  if (applied) {
+    for (const prop of applied.split(",")) {
+      if (prop) {
+        root.style.removeProperty(prop)
+      }
+    }
+    root.removeAttribute(TENANT_THEME_ATTR)
+  }
+
+  restoreDefaultFavicon()
+}
+
+/**
+ * Updates the favicon link element to point to the provided URL.
+ */
+export function updateFavicon(url: string): void {
+  let link = document.querySelector<HTMLLinkElement>("link[rel~='icon']")
+  if (!link) {
+    link = document.createElement("link")
+    link.rel = "icon"
+    document.head.appendChild(link)
+  }
+
+  if (!link.dataset.defaultHref) {
+    link.dataset.defaultHref = link.href
+  }
+
+  link.href = url
+}
+
+function restoreDefaultFavicon(): void {
+  const link = document.querySelector<HTMLLinkElement>("link[rel~='icon']")
+  if (link && link.dataset.defaultHref !== undefined) {
+    link.href = link.dataset.defaultHref
+    delete link.dataset.defaultHref
+  }
+}