feat: Add multi-theme system

.changeset/light-penguins-do.md

@@ -0,0 +1,36 @@
+---
+"@hyperdx/app": minor
+---
+
+feat: Multi-theme system with HyperDX and ClickStack branding support
+
+## Major Features
+
+### Multi-Theme System
+- Add infrastructure for supporting multiple brand themes (HyperDX & ClickStack)
+- Theme switching available in dev/local mode via localStorage
+- Production deployments use `NEXT_PUBLIC_THEME` environment variable (deployment-configured)
+- Each theme provides its own logos, colors, favicons, and default fonts
+
+### Dynamic Favicons
+- Implement theme-aware favicon system with SVG, PNG fallbacks, and Apple Touch Icon
+- Add hydration-safe `DynamicFavicon` component
+- Include XSS protection for theme-color meta tag validation
+
+### Component Refactoring
+- Rename `Icon` → `Logomark` (icon/symbol only)
+- Rename `Logo` → `Wordmark` (icon + text branding)
+- Each theme provides its own `Logomark` and `Wordmark` components
+- Update all component imports across the codebase
+
+### User Preferences Updates
+- Rename `theme` property to `colorMode` to clarify light/dark mode vs brand theme
+- Remove background overlay feature (backgroundEnabled, backgroundUrl, etc.)
+- Add automatic data migration from legacy `theme` → `colorMode` in localStorage
+- Ensure existing users don't lose their preferences during migration
+
+
+### Performance & Type Safety
+- Optimize theme CSS class management (single class swap instead of iterating all themes)
+- Improve type safety in migration function using destructuring
+- Add type guards for runtime validation of localStorage data

packages/app/pages/_app.tsx

@@ -16,18 +16,19 @@ import {
 } from '@tanstack/react-query';
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 
+import { DynamicFavicon } from '@/components/DynamicFavicon';
 import { IS_LOCAL_MODE } from '@/config';
 import {
   DEFAULT_FONT_VAR,
-  DEFAULT_MANTINE_FONT,
   FONT_VAR_MAP,
   MANTINE_FONT_MAP,
 } from '@/config/fonts';
 import { ibmPlexMono, inter, roboto, robotoMono } from '@/fonts';
+import { AppThemeProvider, useAppTheme } from '@/theme/ThemeProvider';
 import { ThemeWrapper } from '@/ThemeWrapper';
 import { useConfirmModal } from '@/useConfirm';
 import { QueryParamProvider as HDXQueryParamProvider } from '@/useQueryParam';
-import { useBackground, useUserPreferences } from '@/useUserPreferences';
+import { useUserPreferences } from '@/useUserPreferences';
 
 import '@mantine/core/styles.css';
 import '@mantine/notifications/styles.css';
@@ -63,13 +64,70 @@ type AppPropsWithLayout = AppProps & {
   Component: NextPageWithLayout;
 };
 
-export default function MyApp({ Component, pageProps }: AppPropsWithLayout) {
+// Component that renders Head content requiring user preferences
+// Must be rendered inside AppThemeProvider to avoid hydration mismatch
+function AppHeadContent() {
+  const { userPreferences } = useUserPreferences();
+  const { theme } = useAppTheme();
+
+  return (
+    <Head>
+      <title>{theme.displayName}</title>
+      <meta name="viewport" content="width=device-width, initial-scale=0.75" />
+      <meta name="google" content="notranslate" />
+      <ColorSchemeScript
+        forceColorScheme={
+          userPreferences.colorMode === 'dark' ? 'dark' : 'light'
+        }
+      />
+    </Head>
+  );
+}
+
+// Component that uses user preferences for theme wrapper
+// Must be rendered inside AppThemeProvider to avoid hydration mismatch
+function AppContent({
+  Component,
+  pageProps,
+  confirmModal,
+}: {
+  Component: NextPageWithLayout;
+  pageProps: AppProps['pageProps'];
+  confirmModal: React.ReactNode;
+}) {
   const { userPreferences } = useUserPreferences();
-  const confirmModal = useConfirmModal();
-  const background = useBackground(userPreferences);
 
-  const selectedMantineFont =
-    MANTINE_FONT_MAP[userPreferences.font] || DEFAULT_MANTINE_FONT;
+  // Only override font if user has explicitly set a preference.
+  // Otherwise, return undefined to let the theme use its default font:
+  // - HyperDX theme: "IBM Plex Sans", monospace
+  // - ClickStack theme: "Inter", sans-serif
+  const selectedMantineFont = userPreferences.font
+    ? MANTINE_FONT_MAP[userPreferences.font] || undefined
+    : undefined;
+
+  useEffect(() => {
+    // Update CSS variable for global font cascading
+    if (typeof document !== 'undefined') {
+      const fontVar = FONT_VAR_MAP[userPreferences.font] || DEFAULT_FONT_VAR;
+      document.documentElement.style.setProperty('--app-font-family', fontVar);
+    }
+  }, [userPreferences.font]);
+
+  const getLayout = Component.getLayout ?? (page => page);
+
+  return (
+    <ThemeWrapper
+      fontFamily={selectedMantineFont}
+      colorScheme={userPreferences.colorMode === 'dark' ? 'dark' : 'light'}
+    >
+      {getLayout(<Component {...pageProps} />)}
+      {confirmModal}
+    </ThemeWrapper>
+  );
+}
+
+export default function MyApp({ Component, pageProps }: AppPropsWithLayout) {
+  const confirmModal = useConfirmModal();
 
   // port to react query ? (needs to wrap with QueryClientProvider)
   useEffect(() => {
@@ -121,47 +179,24 @@ export default function MyApp({ Component, pageProps }: AppPropsWithLayout) {
     }
   }, []);
 
-  useEffect(() => {
-    // Update CSS variable for global font cascading
-    if (typeof document !== 'undefined') {
-      const fontVar = FONT_VAR_MAP[userPreferences.font] || DEFAULT_FONT_VAR;
-      document.documentElement.style.setProperty('--app-font-family', fontVar);
-    }
-  }, [userPreferences.font]);
-
-  const getLayout = Component.getLayout ?? (page => page);
-
   return (
     <React.Fragment>
-      <Head>
-        <title>HyperDX</title>
-        <link rel="icon" type="image/png" sizes="32x32" href="/Icon32.png" />
-        <meta
-          name="viewport"
-          content="width=device-width, initial-scale=0.75"
-        />
-        <meta name="theme-color" content="#25292e"></meta>
-        <meta name="google" content="notranslate" />
-        <ColorSchemeScript
-          forceColorScheme={userPreferences.theme === 'dark' ? 'dark' : 'light'}
-        />
-      </Head>
-
-      <HDXQueryParamProvider>
-        <QueryParamProvider adapter={NextAdapter}>
-          <QueryClientProvider client={queryClient}>
-            <ThemeWrapper
-              fontFamily={selectedMantineFont}
-              colorScheme={userPreferences.theme === 'dark' ? 'dark' : 'light'}
-            >
-              {getLayout(<Component {...pageProps} />)}
-              {confirmModal}
-            </ThemeWrapper>
-            <ReactQueryDevtools initialIsOpen={true} />
-            {background}
-          </QueryClientProvider>
-        </QueryParamProvider>
-      </HDXQueryParamProvider>
+      <AppThemeProvider>
+        <AppHeadContent />
+        <DynamicFavicon />
+        <HDXQueryParamProvider>
+          <QueryParamProvider adapter={NextAdapter}>
+            <QueryClientProvider client={queryClient}>
+              <AppContent
+                Component={Component}
+                pageProps={pageProps}
+                confirmModal={confirmModal}
+              />
+              <ReactQueryDevtools initialIsOpen={true} />
+            </QueryClientProvider>
+          </QueryParamProvider>
+        </HDXQueryParamProvider>
+      </AppThemeProvider>
     </React.Fragment>
   );
 }

packages/app/src/DBServiceMapPage.tsx

@@ -115,7 +115,6 @@ function DBServiceMapPage() {
           <div style={{ minWidth: '200px' }}>
             <Slider
               label={null}
-              color="green"
               min={0}
               max={SAMPLING_FACTORS.length - 1}
               value={SAMPLING_FACTORS.findIndex(

packages/app/src/LandingHeader.tsx

@@ -2,8 +2,8 @@ import Link from 'next/link';
 import { Anchor, Burger, Button, Container, Group } from '@mantine/core';
 import { useDisclosure } from '@mantine/hooks';
 
+import { useWordmark } from './theme/ThemeProvider';
 import api from './api';
-import Logo from './Logo';
 
 export default function LandingHeader({
   activeKey,
@@ -12,6 +12,7 @@ export default function LandingHeader({
   activeKey: string;
   fixed?: boolean;
 }) {
+  const Wordmark = useWordmark();
   const { data: me } = api.useMe();
   const isLoggedIn = Boolean(me);
 
@@ -35,7 +36,7 @@ export default function LandingHeader({
         <Container fluid px="xl" py="md">
           <Group justify="space-between" align="center">
             <Link href="/" style={{ textDecoration: 'none' }}>
-              <Logo />
+              <Wordmark />
             </Link>
 
             <Burger

packages/app/src/OnboardingChecklist.tsx

@@ -20,9 +20,9 @@ import {
 } from '@tabler/icons-react';
 
 import { useQueriedChartConfig } from './hooks/useChartConfig';
+import { useLogomark } from './theme/ThemeProvider';
 import api from './api';
 import { useConnections } from './connection';
-import Icon from './Icon';
 import { useSources } from './source';
 import { useLocalStorage } from './utils';
 
@@ -41,6 +41,7 @@ const OnboardingChecklist = ({
 }: {
   onAddDataClick?: () => void;
 }) => {
+  const Logomark = useLogomark();
   const [isCollapsed, setIsCollapsed] = useLocalStorage(
     'onboardingChecklistCollapsed',
     false,

packages/app/src/Spotlights.tsx

@@ -14,14 +14,15 @@ import {
   IconSettings,
 } from '@tabler/icons-react';
 
+import { useLogomark } from './theme/ThemeProvider';
 import api from './api';
-import Logo from './Icon';
 import { useSavedSearches } from './savedSearch';
 
 import '@mantine/spotlight/styles.css';
 
 export const useSpotlightActions = () => {
   const router = useRouter();
+  const Logomark = useLogomark();
 
   const { data: logViewsData } = useSavedSearches();
   const { data: dashboardsData } = api.useDashboards();
@@ -150,7 +151,7 @@ export const useSpotlightActions = () => {
       {
         id: 'cloud',
         group: 'Menu',
-        leftSection: <Logo />,
+        leftSection: <Logomark size={16} />,
         label: 'HyperDX Cloud',
         description: 'Ready to use HyperDX Cloud? Get started for free.',
         keywords: ['account', 'profile'],
@@ -161,7 +162,7 @@ export const useSpotlightActions = () => {
     );
 
     return logViewActions;
-  }, [logViewsData, dashboardsData, router]);
+  }, [Logomark, logViewsData, dashboardsData, router]);
 
   return { actions };
 };