From 5b410ed9f87daad8e96345a86897f2a9e9419802 Mon Sep 17 00:00:00 2001
From: Luca <102960244+Luca-Timo@users.noreply.github.com>
Date: Tue, 5 May 2026 16:48:47 +0200
Subject: [PATCH] fix(branding): selected-state accent colors, force-mode
 actually flips galleries, compact color picker layout

---
 .../src/components/GlobalThemeProvider.tsx    |  13 +-
 .../components/admin/EmailTemplateEditor.tsx  |   2 +-
 .../src/components/admin/PhotoFilterPanel.tsx |   4 +-
 .../admin/ThemeCustomizerEnhanced.tsx         | 216 ++++++++++--------
 .../src/components/gallery/GalleryView.tsx    |  10 +-
 frontend/src/pages/GalleryPage.tsx            |  10 +-
 frontend/src/pages/admin/BrandingPage.tsx     |   4 +-
 .../src/pages/admin/WebhookDeliveriesPage.tsx |   2 +-
 .../utils/__tests__/themeMigration.test.ts    |  70 +++++-
 frontend/src/utils/themeMigration.ts          |  65 ++++++
 10 files changed, 275 insertions(+), 121 deletions(-)

diff --git a/frontend/src/components/GlobalThemeProvider.tsx b/frontend/src/components/GlobalThemeProvider.tsx
index a5ab63d5..ef84968f 100644
--- a/frontend/src/components/GlobalThemeProvider.tsx
+++ b/frontend/src/components/GlobalThemeProvider.tsx
@@ -1,6 +1,7 @@
 import React, { useEffect, useRef } from 'react';
 import { useTheme } from '../contexts/ThemeContext';
 import { usePublicSettings } from '../hooks/usePublicSettings';
+import { applyForceColorMode } from '../utils/themeMigration';
 
 interface GlobalThemeProviderProps {
   children: React.ReactNode;
@@ -18,14 +19,10 @@ export const GlobalThemeProvider: React.FC<GlobalThemeProviderProps> = ({ childr
 
     if (!themeAppliedRef.current && settingsData?.theme_config && !isGalleryPage) {
       themeAppliedRef.current = true;
-      // Honor instance-wide force color mode: when set, override the
-      // theme's own colorMode so legacy themes can't render light against
-      // a force-dark instance (or vice-versa).
-      const forced = settingsData.branding_force_color_mode;
-      const themeWithForce = forced
-        ? { ...settingsData.theme_config, colorMode: forced }
-        : settingsData.theme_config;
-      setTheme(themeWithForce);
+      // Honor instance-wide force color mode: when set, applyForceColorMode
+      // also swaps the surface/text tokens so the page actually flips
+      // visually (not just the colorMode flag — see #397 follow-up).
+      setTheme(applyForceColorMode(settingsData.theme_config, settingsData.branding_force_color_mode));
     }
   }, [settingsData, setTheme]);
 
diff --git a/frontend/src/components/admin/EmailTemplateEditor.tsx b/frontend/src/components/admin/EmailTemplateEditor.tsx
index 56c3686c..fb2a2089 100644
--- a/frontend/src/components/admin/EmailTemplateEditor.tsx
+++ b/frontend/src/components/admin/EmailTemplateEditor.tsx
@@ -360,7 +360,7 @@ export const EmailTemplateEditor: React.FC<EmailTemplateEditorProps> = ({
           />
           <button
             onClick={addLink}
-            className="px-3 py-1 text-sm bg-primary-600 text-white rounded-md hover:bg-primary-700"
+            className="px-3 py-1 text-sm bg-accent-dark text-white rounded-md hover:bg-primary-700"
             type="button"
           >
             {t('email.editor.addLink')}
diff --git a/frontend/src/components/admin/PhotoFilterPanel.tsx b/frontend/src/components/admin/PhotoFilterPanel.tsx
index be4eed23..bc98b2b0 100644
--- a/frontend/src/components/admin/PhotoFilterPanel.tsx
+++ b/frontend/src/components/admin/PhotoFilterPanel.tsx
@@ -160,7 +160,7 @@ export const PhotoFilterPanel: React.FC<PhotoFilterPanelProps> = ({
                 onClick={() => handleLogicChange('AND')}
                 className={`px-3 py-1 text-sm font-medium transition-colors ${
                   filters.logic === 'AND' || !filters.logic
-                    ? 'bg-primary-600 text-white'
+                    ? 'bg-accent-dark text-white'
                     : 'bg-white dark:bg-neutral-800 text-neutral-600 dark:text-neutral-400 hover:bg-neutral-50 dark:hover:bg-neutral-700'
                 }`}
                 disabled={isLoading}
@@ -172,7 +172,7 @@ export const PhotoFilterPanel: React.FC<PhotoFilterPanelProps> = ({
                 onClick={() => handleLogicChange('OR')}
                 className={`px-3 py-1 text-sm font-medium transition-colors ${
                   filters.logic === 'OR'
-                    ? 'bg-primary-600 text-white'
+                    ? 'bg-accent-dark text-white'
                     : 'bg-white dark:bg-neutral-800 text-neutral-600 dark:text-neutral-400 hover:bg-neutral-50 dark:hover:bg-neutral-700'
                 }`}
                 disabled={isLoading}
diff --git a/frontend/src/components/admin/ThemeCustomizerEnhanced.tsx b/frontend/src/components/admin/ThemeCustomizerEnhanced.tsx
index 5f35cdf7..512dd117 100644
--- a/frontend/src/components/admin/ThemeCustomizerEnhanced.tsx
+++ b/frontend/src/components/admin/ThemeCustomizerEnhanced.tsx
@@ -62,6 +62,45 @@ interface ThemeCustomizerEnhancedProps {
   onForceColorModeChange?: (mode: 'dark' | 'light' | null) => void;
 }
 
+/**
+ * Compact color-picker row used by the 8-token palette.
+ * Renders [Label + Info icon (tooltip)] / [color swatch + hex input].
+ * Help text is hidden in the static layout (lives on the Info icon's title
+ * attribute) so all rows are the same height — keeps the four Surfaces
+ * pickers and the two Accent pickers grid-aligned without forcing the user
+ * to read every help string up front.
+ */
+const ColorPickerRow: React.FC<{
+  label: string;
+  help: string;
+  value: string;
+  fallback: string;
+  onChange: (value: string) => void;
+}> = ({ label, help, value, fallback, onChange }) => (
+  <div>
+    <label className="flex items-center gap-1.5 text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-2">
+      {label}
+      <span className="cursor-help text-neutral-400 dark:text-neutral-500" title={help}>
+        <Info className="w-3.5 h-3.5" />
+      </span>
+    </label>
+    <div className="flex gap-2">
+      <input
+        type="color"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="h-10 w-20 rounded border border-neutral-300 dark:border-neutral-600 cursor-pointer"
+      />
+      <Input
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={fallback}
+        className="flex-1"
+      />
+    </div>
+  </div>
+);
+
 const layoutIcons: Record<GalleryLayoutType, React.ReactNode> = {
   grid: <Grid3X3 className="w-5 h-5" />,
   masonry: <Layers className="w-5 h-5" />,
@@ -262,7 +301,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
               onClick={() => handlePresetSelect(key)}
               className={`relative p-4 rounded-lg border-2 transition-all text-left ${
                 selectedPreset === key
-                  ? 'border-primary-600 bg-primary-50 dark:bg-primary-900/30'
+                  ? 'border-accent-dark bg-primary-50 dark:bg-primary-900/30'
                   : 'border-neutral-200 dark:border-neutral-700 hover:border-neutral-300 dark:hover:border-neutral-600'
               }`}
             >
@@ -274,7 +313,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                   )}
                 </div>
                 {selectedPreset === key && (
-                  <Check className="w-4 h-4 text-primary-600 flex-shrink-0" />
+                  <Check className="w-4 h-4 text-accent-dark flex-shrink-0" />
                 )}
               </div>
               <div className="flex items-center gap-2 mt-3">
@@ -351,7 +390,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                 onClick={() => handleChange('galleryLayout', layout)}
                 className={`relative p-4 rounded-lg border-2 transition-all ${
                   localTheme.galleryLayout === layout
-                    ? 'border-primary-600 bg-primary-50 dark:bg-primary-900/30'
+                    ? 'border-accent-dark bg-primary-50 dark:bg-primary-900/30'
                     : 'border-neutral-200 dark:border-neutral-700 hover:border-neutral-300 dark:hover:border-neutral-600'
                 }`}
               >
@@ -370,7 +409,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                   </span>
                 </div>
                 {localTheme.galleryLayout === layout && (
-                  <Check className="absolute top-2 right-2 w-4 h-4 text-primary-600" />
+                  <Check className="absolute top-2 right-2 w-4 h-4 text-accent-dark" />
                 )}
               </button>
             ))}
@@ -698,7 +737,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                 onClick={() => handleChange('headerStyle', style)}
                 className={`relative p-4 rounded-lg border-2 transition-all ${
                   (localTheme.headerStyle || 'standard') === style
-                    ? 'border-primary-600 bg-primary-50 dark:bg-primary-900/30'
+                    ? 'border-accent-dark bg-primary-50 dark:bg-primary-900/30'
                     : 'border-neutral-200 dark:border-neutral-700 hover:border-neutral-300 dark:hover:border-neutral-600'
                 }`}
               >
@@ -714,7 +753,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                   </span>
                 </div>
                 {(localTheme.headerStyle || 'standard') === style && (
-                  <Check className="absolute top-2 right-2 w-4 h-4 text-primary-600" />
+                  <Check className="absolute top-2 right-2 w-4 h-4 text-accent-dark" />
                 )}
               </button>
             ))}
@@ -737,7 +776,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                     onClick={() => handleChange('heroDividerStyle', divider)}
                     className={`relative p-3 rounded-lg border-2 transition-all ${
                       (localTheme.heroDividerStyle || 'wave') === divider
-                        ? 'border-primary-600 bg-primary-50 dark:bg-primary-900/30'
+                        ? 'border-accent-dark bg-primary-50 dark:bg-primary-900/30'
                         : 'border-neutral-200 dark:border-neutral-700 hover:border-neutral-300 dark:hover:border-neutral-600'
                     }`}
                   >
@@ -751,7 +790,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                       </span>
                     </div>
                     {(localTheme.heroDividerStyle || 'wave') === divider && (
-                      <Check className="absolute top-1 right-1 w-3 h-3 text-primary-600" />
+                      <Check className="absolute top-1 right-1 w-3 h-3 text-accent-dark" />
                     )}
                   </button>
                 ))}
@@ -777,7 +816,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
               onClick={() => handleChange('controlsStyle', 'classic')}
               className={`relative p-4 rounded-lg border-2 transition-all ${
                 (localTheme.controlsStyle || 'classic') === 'classic'
-                  ? 'border-primary-600 bg-primary-50 dark:bg-primary-900/30'
+                  ? 'border-accent-dark bg-primary-50 dark:bg-primary-900/30'
                   : 'border-neutral-200 dark:border-neutral-700 hover:border-neutral-300 dark:hover:border-neutral-600'
               }`}
             >
@@ -793,7 +832,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                 </span>
               </div>
               {(localTheme.controlsStyle || 'classic') === 'classic' && (
-                <Check className="absolute top-2 right-2 w-4 h-4 text-primary-600" />
+                <Check className="absolute top-2 right-2 w-4 h-4 text-accent-dark" />
               )}
             </button>
             <button
@@ -801,7 +840,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
               onClick={() => handleChange('controlsStyle', 'sidebar')}
               className={`relative p-4 rounded-lg border-2 transition-all ${
                 localTheme.controlsStyle === 'sidebar'
-                  ? 'border-primary-600 bg-primary-50 dark:bg-primary-900/30'
+                  ? 'border-accent-dark bg-primary-50 dark:bg-primary-900/30'
                   : 'border-neutral-200 dark:border-neutral-700 hover:border-neutral-300 dark:hover:border-neutral-600'
               }`}
             >
@@ -817,7 +856,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                 </span>
               </div>
               {localTheme.controlsStyle === 'sidebar' && (
-                <Check className="absolute top-2 right-2 w-4 h-4 text-primary-600" />
+                <Check className="absolute top-2 right-2 w-4 h-4 text-accent-dark" />
               )}
             </button>
           </div>
@@ -951,18 +990,29 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
          * coverage only (per user language profile); other locales will
          * show the fallback until reviewed by a native speaker.
          */}
+        {/*
+         * 8-token CI palette pickers, grouped by role. Each picker label
+         * carries an Info icon whose `title` attribute renders the
+         * descriptive help text on hover (or long-press on touch). Keeping
+         * the help out of the static layout means every picker row is the
+         * same height so the four Surfaces and the two Accent rows align
+         * cleanly side-by-side.
+         */}
         <div className="space-y-6">
           {/* Surfaces */}
           <div>
-            <h4 className="text-sm font-semibold text-neutral-700 dark:text-neutral-300 uppercase tracking-wide mb-1">
+            <h4 className="text-sm font-semibold text-neutral-700 dark:text-neutral-300 uppercase tracking-wide mb-3 flex items-center gap-1.5">
               {t('branding.colorGroupSurfaces', 'Surfaces')}
+              <span
+                className="cursor-help text-neutral-400 dark:text-neutral-500"
+                title={t(
+                  'branding.colorGroupSurfacesHelp',
+                  'The neutral layers behind your content. Background sits furthest back; Surface and Elevated stack on top.'
+                )}
+              >
+                <Info className="w-3.5 h-3.5" />
+              </span>
             </h4>
-            <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-3">
-              {t(
-                'branding.colorGroupSurfacesHelp',
-                'The neutral layers behind your content. Background sits furthest back; Surface and Elevated stack on top.'
-              )}
-            </p>
             <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
               {[
                 {
@@ -990,41 +1040,32 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                   fallback: '#e5e5e5',
                 },
               ].map(({ key, label, help, fallback }) => (
-                <div key={key}>
-                  <label className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
-                    {label}
-                  </label>
-                  <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-2">{help}</p>
-                  <div className="flex gap-2">
-                    <input
-                      type="color"
-                      value={(localTheme as Record<string, string | undefined>)[key] || fallback}
-                      onChange={(e) => handleChange(key as keyof ThemeConfig, e.target.value)}
-                      className="h-10 w-20 rounded border border-neutral-300 dark:border-neutral-600 cursor-pointer"
-                    />
-                    <Input
-                      value={(localTheme as Record<string, string | undefined>)[key] || fallback}
-                      onChange={(e) => handleChange(key as keyof ThemeConfig, e.target.value)}
-                      placeholder={fallback}
-                      className="flex-1"
-                    />
-                  </div>
-                </div>
+                <ColorPickerRow
+                  key={key}
+                  label={label}
+                  help={help}
+                  value={(localTheme as Record<string, string | undefined>)[key] || fallback}
+                  fallback={fallback}
+                  onChange={(v) => handleChange(key as keyof ThemeConfig, v)}
+                />
               ))}
             </div>
           </div>
 
           {/* Text */}
           <div>
-            <h4 className="text-sm font-semibold text-neutral-700 dark:text-neutral-300 uppercase tracking-wide mb-1">
+            <h4 className="text-sm font-semibold text-neutral-700 dark:text-neutral-300 uppercase tracking-wide mb-3 flex items-center gap-1.5">
               {t('branding.colorGroupText', 'Text')}
+              <span
+                className="cursor-help text-neutral-400 dark:text-neutral-500"
+                title={t(
+                  'branding.colorGroupTextHelp',
+                  'Foreground text colours. Primary is for everything readers focus on; Secondary is for supporting copy.'
+                )}
+              >
+                <Info className="w-3.5 h-3.5" />
+              </span>
             </h4>
-            <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-3">
-              {t(
-                'branding.colorGroupTextHelp',
-                'Foreground text colours. Primary is for everything readers focus on; Secondary is for supporting copy.'
-              )}
-            </p>
             <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
               {[
                 {
@@ -1040,41 +1081,32 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                   fallback: '#737373',
                 },
               ].map(({ key, label, help, fallback }) => (
-                <div key={key}>
-                  <label className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
-                    {label}
-                  </label>
-                  <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-2">{help}</p>
-                  <div className="flex gap-2">
-                    <input
-                      type="color"
-                      value={(localTheme as Record<string, string | undefined>)[key] || fallback}
-                      onChange={(e) => handleChange(key as keyof ThemeConfig, e.target.value)}
-                      className="h-10 w-20 rounded border border-neutral-300 dark:border-neutral-600 cursor-pointer"
-                    />
-                    <Input
-                      value={(localTheme as Record<string, string | undefined>)[key] || fallback}
-                      onChange={(e) => handleChange(key as keyof ThemeConfig, e.target.value)}
-                      placeholder={fallback}
-                      className="flex-1"
-                    />
-                  </div>
-                </div>
+                <ColorPickerRow
+                  key={key}
+                  label={label}
+                  help={help}
+                  value={(localTheme as Record<string, string | undefined>)[key] || fallback}
+                  fallback={fallback}
+                  onChange={(v) => handleChange(key as keyof ThemeConfig, v)}
+                />
               ))}
             </div>
           </div>
 
           {/* Accent */}
           <div>
-            <h4 className="text-sm font-semibold text-neutral-700 dark:text-neutral-300 uppercase tracking-wide mb-1">
+            <h4 className="text-sm font-semibold text-neutral-700 dark:text-neutral-300 uppercase tracking-wide mb-3 flex items-center gap-1.5">
               {t('branding.colorGroupAccent', 'Accent')}
+              <span
+                className="cursor-help text-neutral-400 dark:text-neutral-500"
+                title={t(
+                  'branding.colorGroupAccentHelp',
+                  'Brand colours that highlight interactive elements. Use a strong colour pair — Accent is for outlines/text, Accent Dark is for filled buttons.'
+                )}
+              >
+                <Info className="w-3.5 h-3.5" />
+              </span>
             </h4>
-            <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-3">
-              {t(
-                'branding.colorGroupAccentHelp',
-                'Brand colours that highlight interactive elements. Use a strong colour pair — Accent is for outlines/text, Accent Dark is for filled buttons.'
-              )}
-            </p>
             <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
               {[
                 {
@@ -1096,26 +1128,14 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                   fallback: '#5C8762',
                 },
               ].map(({ key, label, help, fallback }) => (
-                <div key={key}>
-                  <label className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
-                    {label}
-                  </label>
-                  <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-2">{help}</p>
-                  <div className="flex gap-2">
-                    <input
-                      type="color"
-                      value={(localTheme as Record<string, string | undefined>)[key] || fallback}
-                      onChange={(e) => handleChange(key as keyof ThemeConfig, e.target.value)}
-                      className="h-10 w-20 rounded border border-neutral-300 dark:border-neutral-600 cursor-pointer"
-                    />
-                    <Input
-                      value={(localTheme as Record<string, string | undefined>)[key] || fallback}
-                      onChange={(e) => handleChange(key as keyof ThemeConfig, e.target.value)}
-                      placeholder={fallback}
-                      className="flex-1"
-                    />
-                  </div>
-                </div>
+                <ColorPickerRow
+                  key={key}
+                  label={label}
+                  help={help}
+                  value={(localTheme as Record<string, string | undefined>)[key] || fallback}
+                  fallback={fallback}
+                  onChange={(v) => handleChange(key as keyof ThemeConfig, v)}
+                />
               ))}
             </div>
             {/* primaryColor is kept in sync with accentDarkColor inside
@@ -1273,14 +1293,14 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
               onClick={() => onCssTemplateChange(null)}
               className={`relative p-4 rounded-lg border-2 transition-all text-left ${
                 !cssTemplateId
-                  ? 'border-primary-600 bg-primary-50 dark:bg-primary-900/30'
+                  ? 'border-accent-dark bg-primary-50 dark:bg-primary-900/30'
                   : 'border-neutral-200 dark:border-neutral-700 hover:border-neutral-300 dark:hover:border-neutral-600'
               }`}
             >
               <div className="flex items-center justify-between">
                 <span className="font-medium text-sm text-neutral-900 dark:text-neutral-100">{t('branding.noTemplate', 'No Template')}</span>
                 {!cssTemplateId && (
-                  <Check className="w-4 h-4 text-primary-600 flex-shrink-0" />
+                  <Check className="w-4 h-4 text-accent-dark flex-shrink-0" />
                 )}
               </div>
               <span className="text-xs text-neutral-600 dark:text-neutral-400 mt-1 block">
@@ -1295,14 +1315,14 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
                 onClick={() => onCssTemplateChange(template.id)}
                 className={`relative p-4 rounded-lg border-2 transition-all text-left ${
                   cssTemplateId === template.id
-                    ? 'border-primary-600 bg-primary-50 dark:bg-primary-900/30'
+                    ? 'border-accent-dark bg-primary-50 dark:bg-primary-900/30'
                     : 'border-neutral-200 dark:border-neutral-700 hover:border-neutral-300 dark:hover:border-neutral-600'
                 }`}
               >
                 <div className="flex items-center justify-between">
                   <span className="font-medium text-sm text-neutral-900 dark:text-neutral-100">{template.name}</span>
                   {cssTemplateId === template.id && (
-                    <Check className="w-4 h-4 text-primary-600 flex-shrink-0" />
+                    <Check className="w-4 h-4 text-accent-dark flex-shrink-0" />
                   )}
                 </div>
                 <span className="text-xs text-neutral-600 dark:text-neutral-400 mt-1 block">
@@ -1326,7 +1346,7 @@ export const ThemeCustomizerEnhanced: React.FC<ThemeCustomizerEnhancedProps> = (
           <button
             type="button"
             onClick={() => setShowCssInstructions(!showCssInstructions)}
-            className="flex items-center gap-2 text-sm text-primary-600 hover:text-primary-700 font-medium"
+            className="flex items-center gap-2 text-sm text-accent hover:opacity-80 font-medium"
           >
             <Info className="w-4 h-4" />
             {t('branding.cssInstructions.title', 'How to use Custom CSS')}
diff --git a/frontend/src/components/gallery/GalleryView.tsx b/frontend/src/components/gallery/GalleryView.tsx
index 18d6ba0c..99533262 100644
--- a/frontend/src/components/gallery/GalleryView.tsx
+++ b/frontend/src/components/gallery/GalleryView.tsx
@@ -28,6 +28,7 @@ import { useGalleryCustomCss } from '../../hooks/useGalleryCustomCss';
 import { usePublicSettings } from '../../hooks/usePublicSettings';
 import type { Photo } from '../../types';
 import { GALLERY_THEME_PRESETS } from '../../types/theme.types';
+import { applyForceColorMode } from '../../utils/themeMigration';
 import { useQueryClient } from '@tanstack/react-query';
 
 interface GalleryViewProps {
@@ -342,10 +343,11 @@ export const GalleryView: React.FC<GalleryViewProps> = ({ slug, event }) => {
       }
 
       // Honor instance-wide force color mode (Branding > Force color mode).
-      // The branding-level lock wins over per-event themes so a force-dark
-      // instance never accidentally renders a light gallery (and vice-versa).
-      if (themeToApply && settingsData.branding_force_color_mode) {
-        themeToApply = { ...themeToApply, colorMode: settingsData.branding_force_color_mode };
+      // applyForceColorMode pins colorMode AND swaps surface/text tokens
+      // when the active theme doesn't natively support the locked mode,
+      // so the gallery actually flips visually (#397 follow-up).
+      if (themeToApply) {
+        themeToApply = applyForceColorMode(themeToApply, settingsData.branding_force_color_mode);
       }
 
       // Apply theme with a small delay to ensure it overrides any global theme
diff --git a/frontend/src/pages/GalleryPage.tsx b/frontend/src/pages/GalleryPage.tsx
index 1adc8f65..d990c933 100644
--- a/frontend/src/pages/GalleryPage.tsx
+++ b/frontend/src/pages/GalleryPage.tsx
@@ -14,6 +14,7 @@ import { GallerySkeleton } from '../components/gallery/GallerySkeleton';
 import { analyticsService } from '../services/analytics.service';
 import { galleryService } from '../services';
 import { GALLERY_THEME_PRESETS } from '../types/theme.types';
+import { applyForceColorMode } from '../utils/themeMigration';
 import { buildResourceUrl } from '../utils/url';
 import { isGalleryPublic, normalizeRequirePassword } from '../utils/accessControl';
 
@@ -158,10 +159,11 @@ export const GalleryPage: React.FC = () => {
       }
 
       // Honor instance-wide force color mode (Branding > Force color mode).
-      // When set, override per-event/per-theme colorMode so no gallery can
-      // render light against a force-dark instance.
-      if (themeToApply && settingsData.branding_force_color_mode) {
-        themeToApply = { ...themeToApply, colorMode: settingsData.branding_force_color_mode };
+      // applyForceColorMode pins colorMode AND swaps surface/text tokens
+      // when the active theme doesn't natively support the locked mode,
+      // so the gallery actually flips visually (#397 follow-up).
+      if (themeToApply) {
+        themeToApply = applyForceColorMode(themeToApply, settingsData.branding_force_color_mode);
       }
 
       // Apply theme
diff --git a/frontend/src/pages/admin/BrandingPage.tsx b/frontend/src/pages/admin/BrandingPage.tsx
index e1a4dcc0..b3d3d05b 100644
--- a/frontend/src/pages/admin/BrandingPage.tsx
+++ b/frontend/src/pages/admin/BrandingPage.tsx
@@ -494,7 +494,7 @@ export const BrandingPage: React.FC = () => {
                       onClick={() => handleBrandingChange('logo_position', position)}
                       className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${
                         brandingSettings.logo_position === position
-                          ? 'bg-primary-600 text-white'
+                          ? 'bg-accent-dark text-white'
                           : 'bg-neutral-100 dark:bg-neutral-700 text-neutral-700 dark:text-neutral-300 hover:bg-neutral-200 dark:hover:bg-neutral-600'
                       }`}
                     >
@@ -665,7 +665,7 @@ export const BrandingPage: React.FC = () => {
                       onClick={() => handleBrandingChange('watermark_position', position.value)}
                       className={`px-3 py-2 text-sm rounded-lg border transition-colors ${
                         brandingSettings.watermark_position === position.value
-                          ? 'bg-primary-600 text-white border-primary-600'
+                          ? 'bg-accent-dark text-white border-accent-dark'
                           : 'bg-white dark:bg-neutral-800 text-neutral-700 dark:text-neutral-300 border-neutral-300 dark:border-neutral-600 hover:bg-neutral-50 dark:hover:bg-neutral-700'
                       }`}
                     >
diff --git a/frontend/src/pages/admin/WebhookDeliveriesPage.tsx b/frontend/src/pages/admin/WebhookDeliveriesPage.tsx
index 11172ccf..31259995 100644
--- a/frontend/src/pages/admin/WebhookDeliveriesPage.tsx
+++ b/frontend/src/pages/admin/WebhookDeliveriesPage.tsx
@@ -195,7 +195,7 @@ export const WebhookDeliveriesPage: React.FC = () => {
               onClick={() => setFilter(s)}
               className={`text-xs px-3 py-1 rounded-full ${
                 filter === s
-                  ? 'bg-primary-600 text-white'
+                  ? 'bg-accent-dark text-white'
                   : 'bg-neutral-100 dark:bg-neutral-800 text-neutral-600 dark:text-neutral-400 hover:bg-neutral-200'
               }`}
             >
diff --git a/frontend/src/utils/__tests__/themeMigration.test.ts b/frontend/src/utils/__tests__/themeMigration.test.ts
index 6517b009..62c73904 100644
--- a/frontend/src/utils/__tests__/themeMigration.test.ts
+++ b/frontend/src/utils/__tests__/themeMigration.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { migrateThemeConfig } from '../themeMigration';
+import { migrateThemeConfig, applyForceColorMode } from '../themeMigration';
 import type { ThemeConfig } from '../../types/theme.types';
 
 describe('migrateThemeConfig — 8-token palette fill', () => {
@@ -89,3 +89,71 @@ describe('migrateThemeConfig — 8-token palette fill', () => {
     expect(migrated.accentDarkColor).toBe('#5C8762');
   });
 });
+
+describe('applyForceColorMode', () => {
+  const lightTheme: ThemeConfig = {
+    primaryColor: '#5C8762',
+    accentColor: '#22c55e',
+    accentDarkColor: '#5C8762',
+    backgroundColor: '#fafafa',
+    surfaceColor: '#ffffff',
+    elevatedColor: '#f5f5f5',
+    surfaceBorderColor: '#e5e5e5',
+    textColor: '#171717',
+    mutedTextColor: '#737373',
+    colorMode: 'light',
+  };
+
+  const lbmDark: ThemeConfig = {
+    primaryColor: '#014E4E',
+    accentColor: '#017C7C',
+    accentDarkColor: '#014E4E',
+    backgroundColor: '#0D0D0D',
+    surfaceColor: '#111414',
+    elevatedColor: '#182222',
+    surfaceBorderColor: '#1E2E2E',
+    textColor: '#EBEBEB',
+    mutedTextColor: '#4A6060',
+    colorMode: 'dark',
+  };
+
+  it('returns the theme unchanged when no force mode is set', () => {
+    expect(applyForceColorMode(lightTheme, null)).toEqual(lightTheme);
+    expect(applyForceColorMode(lightTheme, undefined)).toEqual(lightTheme);
+  });
+
+  it('only pins colorMode when the theme already matches the forced mode', () => {
+    const result = applyForceColorMode(lbmDark, 'dark');
+    expect(result.colorMode).toBe('dark');
+    // LBM surfaces preserved.
+    expect(result.backgroundColor).toBe('#0D0D0D');
+    expect(result.surfaceColor).toBe('#111414');
+    expect(result.accentColor).toBe('#017C7C');
+  });
+
+  it('swaps surface tokens when forcing a light theme to dark', () => {
+    const result = applyForceColorMode(lightTheme, 'dark');
+    expect(result.colorMode).toBe('dark');
+    // Surfaces flipped to dark defaults.
+    expect(result.backgroundColor).toBe('#0f0f0f');
+    expect(result.surfaceColor).toBe('#1a1a1a');
+    expect(result.elevatedColor).toBe('#242424');
+    expect(result.surfaceBorderColor).toBe('#2e2e2e');
+    expect(result.textColor).toBe('#e5e5e5');
+    expect(result.mutedTextColor).toBe('#a3a3a3');
+    // Brand identity preserved.
+    expect(result.accentColor).toBe('#22c55e');
+    expect(result.accentDarkColor).toBe('#5C8762');
+  });
+
+  it('swaps surface tokens when forcing a dark theme to light', () => {
+    const result = applyForceColorMode(lbmDark, 'light');
+    expect(result.colorMode).toBe('light');
+    expect(result.backgroundColor).toBe('#fafafa');
+    expect(result.surfaceColor).toBe('#ffffff');
+    expect(result.textColor).toBe('#171717');
+    // LBM accent colours survive the flip.
+    expect(result.accentColor).toBe('#017C7C');
+    expect(result.accentDarkColor).toBe('#014E4E');
+  });
+});
diff --git a/frontend/src/utils/themeMigration.ts b/frontend/src/utils/themeMigration.ts
index 0ad31ec4..37f9b424 100644
--- a/frontend/src/utils/themeMigration.ts
+++ b/frontend/src/utils/themeMigration.ts
@@ -1,5 +1,70 @@
 import type { ThemeConfig, HeaderStyleType, HeroDividerStyle, GalleryLayoutType } from '../types/theme.types';
 
+/**
+ * Surface defaults for the two color modes — the same values applyTheme()
+ * falls back to when a theme has no explicit surface/elevated/border/text
+ * tokens. Exposed here so the force-color-mode helper can swap them
+ * wholesale when an admin locks the instance to a mode that the active
+ * theme doesn't natively support.
+ */
+const DARK_SURFACE_DEFAULTS = {
+  backgroundColor: '#0f0f0f',
+  surfaceColor: '#1a1a1a',
+  elevatedColor: '#242424',
+  surfaceBorderColor: '#2e2e2e',
+  textColor: '#e5e5e5',
+  mutedTextColor: '#a3a3a3',
+};
+
+const LIGHT_SURFACE_DEFAULTS = {
+  backgroundColor: '#fafafa',
+  surfaceColor: '#ffffff',
+  elevatedColor: '#f5f5f5',
+  surfaceBorderColor: '#e5e5e5',
+  textColor: '#171717',
+  mutedTextColor: '#737373',
+};
+
+/**
+ * Apply an instance-wide force color mode lock to a theme config.
+ *
+ * If the theme already matches the locked mode (or no lock is set), only
+ * the colorMode flag is pinned. If the theme is locked to a mode it
+ * doesn't natively support (e.g. an admin set Force Dark but is opening
+ * a light gallery preset), the surface/text tokens are replaced with the
+ * matching mode's defaults — the user's accent/accentDark colours are
+ * preserved so brand identity survives the flip.
+ *
+ * Centralised here so GlobalThemeProvider, GalleryPage and GalleryView
+ * stay in sync (#397 follow-up: galleries did not visibly flip when
+ * Force Dark/Light was toggled because only colorMode was overridden,
+ * leaving the original light/dark surface colours in place).
+ */
+export function applyForceColorMode(
+  theme: ThemeConfig,
+  forced: 'dark' | 'light' | null | undefined
+): ThemeConfig {
+  if (!forced) return theme;
+
+  const themeMode = theme.colorMode === 'auto'
+    ? (typeof window !== 'undefined'
+        && window.matchMedia('(prefers-color-scheme: dark)').matches
+          ? 'dark'
+          : 'light')
+    : (theme.colorMode || 'light');
+
+  if (themeMode === forced) {
+    return { ...theme, colorMode: forced };
+  }
+
+  const surfaces = forced === 'dark' ? DARK_SURFACE_DEFAULTS : LIGHT_SURFACE_DEFAULTS;
+  return {
+    ...theme,
+    ...surfaces,
+    colorMode: forced,
+  };
+}
+
 /**
  * Fills in any missing 8-token CI palette fields on legacy themes that were
  * saved before the palette expanded from 4 → 8 explicit tokens.