feat(FR-1580): Implement custom theme preview mode feature (#4653)

### Add Theme Preview Mode and Export Functionality

Adds functionality for users to directly change the theme of the WebUI. Since the API for saving settings is not yet supported, currently only extraction to a JSON-formatted file is possible. Theme settings support a preview window; if the preview page is open, changing values in the origin window automatically applies them to the preview window.

This PR enhances the theme customization experience by adding:

1. A theme preview mode that allows users to see their theme changes in a new window without affecting their current session
2. The ability to export custom theme configurations as JSON files
3. Warning alerts to inform users about theme preview mode and application process

The implementation includes:
- A new "Preview" button that opens a new window with the custom theme applied
- An "Export JSON" button to download the current theme configuration
- A warning alert explaining that theme changes require support team assistance to apply
- A notification banner that appears when in preview mode
- Session storage management to track preview mode state
- Event listeners to automatically refresh preview windows when theme settings change

[Screen Recording 2025-11-17 at 5.07.41 PM.mov <span class="graphite__hidden">(uploaded via Graphite)</span> <img class="graphite__hidden" src="https://app.graphite.com/user-attachments/thumbnails/610104d6-130d-4392-a7f1-f3c67d1cdc1b.mov" />](https://app.graphite.com/user-attachments/video/610104d6-130d-4392-a7f1-f3c67d1cdc1b.mov)

**Checklist:**

- [ ] Documentation
- [ ] Minium required manager version
- [ ] Specific setting for review (eg., KB link, endpoint or how to setup)
- [ ] Minimum requirements to check during review
- [ ] Test case(s) to demonstrate the difference of before/after

Author: ironAiken2

react/src/components/BrandingSettingList.tsx

@@ -1,24 +1,38 @@
+import BAIAlert from './BAIAlert';
 import ThemeColorPicker from './BrandingSettingItems/ThemeColorPicker';
 import SettingList, { SettingGroup } from './SettingList';
-import { BAIButton } from 'backend.ai-ui';
+import { ExportOutlined } from '@ant-design/icons';
+import { App } from 'antd';
+import { BAIButton, BAIFlex } from 'backend.ai-ui';
+import _ from 'lodash';
 import { useTranslation } from 'react-i18next';
+import { downloadBlob } from 'src/helper/csv-util';
 import { useBAISettingUserState } from 'src/hooks/useBAISetting';
 
 interface BrandingSettingListProps {}
 
 const BrandingSettingList: React.FC<BrandingSettingListProps> = () => {
   const { t } = useTranslation();
+  const { message } = App.useApp();
 
-  const [, setUserCustomThemeConfig] = useBAISettingUserState(
-    'custom_theme_config',
-  );
+  const [userCustomThemeConfig, setUserCustomThemeConfig] =
+    useBAISettingUserState('custom_theme_config');
 
   const settingGroups: Array<SettingGroup> = [
     {
       'data-testid': 'group-theme-customization',
       title: t('userSettings.Theme'),
       titleExtra: (
-        <BAIButton size="small">{t('userSettings.theme.Preview')}</BAIButton>
+        <BAIButton
+          size="small"
+          action={async () => {
+            const previewWindow = window.open(window.location.origin, '_blank');
+            previewWindow?.sessionStorage.setItem('isThemePreviewMode', 'true');
+            previewWindow?.location.reload();
+          }}
+        >
+          {t('userSettings.theme.Preview')}
+        </BAIButton>
       ),
       settingItems: [
         {
@@ -82,7 +96,40 @@ const BrandingSettingList: React.FC<BrandingSettingListProps> = () => {
     },
   ];
 
-  return <SettingList settingGroups={settingGroups} showSearchBar />;
+  return (
+    <BAIFlex direction="column" gap="md" align="stretch">
+      <BAIAlert
+        description={t('userSettings.theme.CustomThemeSettingAlert')}
+        type="warning"
+        showIcon
+      />
+      <SettingList
+        showSearchBar
+        showResetButton
+        settingGroups={settingGroups}
+        primaryButton={
+          <BAIButton
+            type="primary"
+            icon={<ExportOutlined />}
+            action={async () => {
+              if (_.isEmpty(userCustomThemeConfig)) {
+                message.error(t('userSettings.theme.NoChangesMade'));
+                return;
+              }
+
+              const blob = new Blob(
+                [JSON.stringify(userCustomThemeConfig, null, 2)],
+                { type: 'application/json' },
+              );
+              downloadBlob(blob, `theme.json`);
+            }}
+          >
+            {t('theme.button.ExportToJson')}
+          </BAIButton>
+        }
+      />
+    </BAIFlex>
+  );
 };
 
 export default BrandingSettingList;

react/src/components/DefaultProviders.tsx

@@ -13,7 +13,7 @@ import { ThemeModeProvider, useThemeMode } from '../hooks/useThemeMode';
 import indexCss from '../index.css?raw';
 import { StyleProvider, createCache } from '@ant-design/cssinjs';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { useUpdateEffect } from 'ahooks';
+import { useSessionStorageState, useUpdateEffect } from 'ahooks';
 import { App, AppProps, theme, Typography } from 'antd';
 import { BAIConfigProvider } from 'backend.ai-ui';
 import dayjs from 'dayjs';
@@ -47,17 +47,20 @@ import weekday from 'dayjs/plugin/weekday';
 import i18n from 'i18next';
 import Backend from 'i18next-http-backend';
 import { createStore, Provider as JotaiProvider } from 'jotai';
+import _ from 'lodash';
 import { GlobeIcon } from 'lucide-react';
 import React, {
   Suspense,
   useEffect,
+  useEffectEvent,
   useLayoutEffect,
   useMemo,
   useState,
 } from 'react';
 import { useTranslation, initReactI18next } from 'react-i18next';
 import { RelayEnvironmentProvider } from 'react-relay/hooks';
 import { BrowserRouter, useLocation, useNavigate } from 'react-router-dom';
+import { useBAISettingUserState } from 'src/hooks/useBAISetting';
 import { QueryParamProvider } from 'use-query-params';
 import { ReactRouter6Adapter } from 'use-query-params/adapters/react-router-6';
 
@@ -205,7 +208,34 @@ const DefaultProvidersForWebComponent: React.FC<DefaultProvidersProps> = ({
 }) => {
   const cache = useMemo(() => createCache(), []);
   const [lang] = useCurrentLanguage();
+
+  const [userCustomThemeConfig] = useBAISettingUserState('custom_theme_config');
+  const [isThemePreviewMode] = useSessionStorageState('isThemePreviewMode', {
+    defaultValue: false,
+  });
   const themeConfig = useCustomThemeConfig();
+  const defaultThemeConfig =
+    isThemePreviewMode && !_.isEmpty(userCustomThemeConfig)
+      ? userCustomThemeConfig
+      : themeConfig;
+
+  const reloadPreviewWindow = useEffectEvent(() => {
+    if (!isThemePreviewMode) return;
+
+    const handleLocalStorageChange = (e: StorageEvent) => {
+      if (e.key === 'backendaiwebui.settings.user.custom_theme_config') {
+        window.location.reload();
+      }
+    };
+    window.addEventListener('storage', handleLocalStorageChange);
+    return () =>
+      window.removeEventListener('storage', handleLocalStorageChange);
+  });
+
+  useEffect(() => {
+    reloadPreviewWindow();
+  }, []);
+
   const { isDarkMode } = useThemeMode();
 
   const componentValues = useMemo(() => {
@@ -249,8 +279,8 @@ const DefaultProvidersForWebComponent: React.FC<DefaultProvidersProps> = ({
                       }}
                       theme={{
                         ...(isDarkMode
-                          ? { ...themeConfig?.dark }
-                          : { ...themeConfig?.light }),
+                          ? { ...defaultThemeConfig?.dark }
+                          : { ...defaultThemeConfig?.light }),
                         algorithm: isDarkMode
                           ? theme.darkAlgorithm
                           : theme.defaultAlgorithm,
@@ -325,9 +355,35 @@ export const DefaultProvidersForReactRoot: React.FC<
   Partial<DefaultProvidersProps>
 > = ({ children }) => {
   const [lang] = useCurrentLanguage();
-  const themeConfig = useCustomThemeConfig();
   const { isDarkMode } = useThemeMode();
 
+  const [userCustomThemeConfig] = useBAISettingUserState('custom_theme_config');
+  const [isThemePreviewMode] = useSessionStorageState('isThemePreviewMode', {
+    defaultValue: false,
+  });
+  const themeConfig = useCustomThemeConfig();
+  const defaultThemeConfig =
+    isThemePreviewMode && !_.isEmpty(userCustomThemeConfig)
+      ? userCustomThemeConfig
+      : themeConfig;
+
+  const reloadPreviewWindow = useEffectEvent(() => {
+    if (!isThemePreviewMode) return;
+
+    const handleLocalStorageChange = (e: StorageEvent) => {
+      if (e.key === 'backendaiwebui.settings.user.custom_theme_config') {
+        window.location.reload();
+      }
+    };
+    window.addEventListener('storage', handleLocalStorageChange);
+    return () =>
+      window.removeEventListener('storage', handleLocalStorageChange);
+  });
+
+  useEffect(() => {
+    reloadPreviewWindow();
+  }, []);
+
   return (
     <>
       <style>{indexCss}</style>
@@ -341,8 +397,8 @@ export const DefaultProvidersForReactRoot: React.FC<
               }
               theme={{
                 ...(isDarkMode
-                  ? { ...themeConfig?.dark }
-                  : { ...themeConfig?.light }),
+                  ? { ...defaultThemeConfig?.dark }
+                  : { ...defaultThemeConfig?.light }),
                 algorithm: isDarkMode
                   ? theme.darkAlgorithm
                   : theme.defaultAlgorithm,

react/src/components/MainLayout/MainLayout.tsx

@@ -10,6 +10,7 @@ import ForceTOTPChecker from '../ForceTOTPChecker';
 import NetworkStatusBanner from '../NetworkStatusBanner';
 import NoResourceGroupAlert from '../NoResourceGroupAlert';
 import PasswordChangeRequestAlert from '../PasswordChangeRequestAlert';
+import ThemePreviewModeAlert from '../ThemePreviewModeAlert';
 import { DRAWER_WIDTH } from '../WEBUINotificationDrawer';
 import WebUIBreadcrumb from '../WebUIBreadcrumb';
 import WebUIHeader from './WebUIHeader';
@@ -235,6 +236,7 @@ function MainLayout() {
                   align="stretch"
                   className={styles.alertWrapper}
                 >
+                  <ThemePreviewModeAlert />
                   <ErrorBoundaryWithNullFallback>
                     <NoResourceGroupAlert />
                   </ErrorBoundaryWithNullFallback>

react/src/components/SettingList.tsx

@@ -3,7 +3,6 @@ import { RedoOutlined, SearchOutlined } from '@ant-design/icons';
 import { useToggle } from 'ahooks';
 import {
   Alert,
-  Button,
   Checkbox,
   Divider,
   Empty,
@@ -13,9 +12,9 @@ import {
   theme,
 } from 'antd';
 import { createStyles } from 'antd-style';
-import { BAIModal, BAIFlex } from 'backend.ai-ui';
+import { BAIModal, BAIFlex, BAIButton } from 'backend.ai-ui';
 import _ from 'lodash';
-import { useState, ReactNode } from 'react';
+import React, { useState, ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
 
 const useStyles = createStyles(({ css }) => ({
@@ -35,6 +34,7 @@ export type SettingGroup = {
   titleExtra?: ReactNode;
   description?: ReactNode;
   settingItems: SettingItemProps[];
+  alert?: ReactNode;
 };
 
 interface SettingPageProps {
@@ -43,6 +43,8 @@ interface SettingPageProps {
   showChangedOptionFilter?: boolean;
   showResetButton?: boolean;
   showSearchBar?: boolean;
+  primaryButton?: ReactNode;
+  extraButton?: ReactNode;
 }
 
 const TabTitle: React.FC<{
@@ -108,6 +110,7 @@ const GroupSettingItems: React.FC<
         )}
       </BAIFlex>
       <BAIFlex direction="column" align="stretch" gap={'lg'}>
+        {group.alert}
         {group.settingItems.map((item, idx) => (
           <SettingItem key={item.title + idx} {...item} />
         ))}
@@ -122,6 +125,8 @@ const SettingList: React.FC<SettingPageProps> = ({
   showChangedOptionFilter,
   showResetButton,
   showSearchBar,
+  primaryButton,
+  extraButton,
 }) => {
   'use memo';
 
@@ -180,14 +185,16 @@ const SettingList: React.FC<SettingPageProps> = ({
               {t('settings.ShowOnlyChanged')}
             </Checkbox>
           )}
+          {extraButton}
           {!!showResetButton && (
-            <Button
+            <BAIButton
               icon={<RedoOutlined />}
               onClick={() => setIsOpenResetChangesModal()}
             >
               {t('button.Reset')}
-            </Button>
+            </BAIButton>
           )}
+          {primaryButton}
         </BAIFlex>
         <Tabs
           activeKey={activeTabKey}
@@ -241,21 +248,24 @@ const SettingList: React.FC<SettingPageProps> = ({
                   count={group.settingItems.length}
                 />
               ),
-              children:
-                group.settingItems.length > 0 ? (
-                  <GroupSettingItems
-                    group={group}
-                    hideEmpty
-                    onReset={() => {
-                      setIsOpenResetChangesModal();
-                    }}
-                  />
-                ) : (
-                  <Empty
-                    image={Empty.PRESENTED_IMAGE_SIMPLE}
-                    description={t('settings.NoChangesToDisplay')}
-                  />
-                ),
+              children: (
+                <BAIFlex direction="column" align="stretch" gap={'xl'}>
+                  {group.settingItems.length > 0 ? (
+                    <GroupSettingItems
+                      group={group}
+                      hideEmpty
+                      onReset={() => {
+                        setIsOpenResetChangesModal();
+                      }}
+                    />
+                  ) : (
+                    <Empty
+                      image={Empty.PRESENTED_IMAGE_SIMPLE}
+                      description={t('settings.NoChangesToDisplay')}
+                    />
+                  )}
+                </BAIFlex>
+              ),
             })),
           ]}
         />

react/src/components/ThemePreviewModeAlert.tsx

@@ -0,0 +1,18 @@
+import BAIAlert, { BAIAlertProps } from './BAIAlert';
+import { useSessionStorageState } from 'ahooks';
+import { useTranslation } from 'react-i18next';
+
+interface ThemePreviewModeAlertProps extends BAIAlertProps {}
+
+const ThemePreviewModeAlert: React.FC<ThemePreviewModeAlertProps> = () => {
+  const { t } = useTranslation();
+  const [isThemePreviewMode] = useSessionStorageState('isThemePreviewMode', {
+    defaultValue: false,
+  });
+
+  return isThemePreviewMode ? (
+    <BAIAlert showIcon type="warning" message={t('theme.PreviewModeAlert')} />
+  ) : null;
+};
+
+export default ThemePreviewModeAlert;

react/src/pages/ConfigurationsPage.tsx

@@ -1,5 +1,7 @@
 import ConfigurationsSettingList from '../components/ConfigurationsSettingList';
+import { useSessionStorageState } from 'ahooks';
 import { Card, Skeleton } from 'antd';
+import { filterOutEmpty } from 'backend.ai-ui';
 import { Suspense } from 'react';
 import { useTranslation } from 'react-i18next';
 import BAIErrorBoundary from 'src/components/BAIErrorBoundary';
@@ -13,21 +15,24 @@ const tabParam = withDefault(StringParam, 'configurations');
 const ConfigurationsPage = () => {
   const { t } = useTranslation();
   const [curTabKey, setCurTabKey] = useQueryParam('tab', tabParam);
+  const [isThemePreviewMode] = useSessionStorageState('isThemePreviewMode', {
+    defaultValue: false,
+  });
 
   return (
     <Card
       activeTabKey={curTabKey}
       onTabChange={(key) => setCurTabKey(key as TabKey)}
-      tabList={[
+      tabList={filterOutEmpty([
         {
           key: 'configurations',
           tab: t('webui.menu.Configurations'),
         },
-        {
+        !isThemePreviewMode && {
           key: 'branding',
           tab: t('webui.menu.Branding'),
         },
-      ]}
+      ])}
     >
       <Suspense fallback={<Skeleton active />}>
         {curTabKey === 'configurations' && (