From fe3e9deb330e1a45288600560ca68ec9558d20c7 Mon Sep 17 00:00:00 2001
From: Yueying Lu <lyueying@amazon.com>
Date: Tue, 11 Aug 2026 23:28:32 +0200
Subject: [PATCH] feat: Add skipVisualRefresh option in initThemes

---
 .../use-runtime-visual-refresh.test.tsx       | 26 +++++++++++++++++++
 src/internal/visual-mode/index.ts             | 18 +++++++++++--
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/src/internal/visual-mode/__tests__/use-runtime-visual-refresh.test.tsx b/src/internal/visual-mode/__tests__/use-runtime-visual-refresh.test.tsx
index 3702430..a11b0ec 100644
--- a/src/internal/visual-mode/__tests__/use-runtime-visual-refresh.test.tsx
+++ b/src/internal/visual-mode/__tests__/use-runtime-visual-refresh.test.tsx
@@ -158,5 +158,31 @@ describe('useVisualRefresh', () => {
       initThemes();
       expect(console.warn).toHaveBeenCalledWith(expect.stringMatching(/Multiple theme flags are enabled/));
     });
+
+    test('skips visual-refresh class when skipVisualRefresh is true', () => {
+      window[awsuiVisualRefreshFlag] = () => true;
+      initThemes({ skipVisualRefresh: true });
+      expect(document.body).not.toHaveClass('awsui-visual-refresh');
+    });
+
+    test('adds one-theme class when skipVisualRefresh is true and oneTheme flag is set', () => {
+      (window as any)[awsuiGlobalFlagsSymbol] = { oneTheme: true };
+      initThemes({ skipVisualRefresh: true });
+      expect(document.body).toHaveClass('awsui-one-theme');
+    });
+
+    test('adds one-theme class and skips visual-refresh when both flags set and skipVisualRefresh is true', () => {
+      window[awsuiVisualRefreshFlag] = () => true;
+      (window as any)[awsuiGlobalFlagsSymbol] = { oneTheme: true };
+      initThemes({ skipVisualRefresh: true });
+      expect(document.body).toHaveClass('awsui-one-theme');
+      expect(document.body).not.toHaveClass('awsui-visual-refresh');
+    });
+
+    test('does not skip visual-refresh class when skipVisualRefresh is false', () => {
+      window[awsuiVisualRefreshFlag] = () => true;
+      initThemes({ skipVisualRefresh: false });
+      expect(document.body).toHaveClass('awsui-visual-refresh');
+    });
   });
 });
diff --git a/src/internal/visual-mode/index.ts b/src/internal/visual-mode/index.ts
index 10cfa6f..0a3a359 100644
--- a/src/internal/visual-mode/index.ts
+++ b/src/internal/visual-mode/index.ts
@@ -132,8 +132,22 @@ function applyThemeClassName(theme: Theme) {
   }
 }
 
-export function initThemes() {
-  const flaggedThemes = themePrecedence.filter(theme => themeDefinitions[theme].isFlagActive());
+export interface InitThemesOptions {
+  /**
+   * When true, skip applying the visual-refresh body class.
+   * Use this for packages where visual refresh styles are always active (ALWAYS_VISUAL_REFRESH mode),
+   * so the body class is unnecessary — only one-theme class will be applied.
+   */
+  skipVisualRefresh?: boolean;
+}
+
+export function initThemes(options?: InitThemesOptions) {
+  const flaggedThemes = themePrecedence.filter(theme => {
+    if (options?.skipVisualRefresh && theme === Theme.VisualRefresh) {
+      return false;
+    }
+    return themeDefinitions[theme].isFlagActive();
+  });
   if (isDevelopment && flaggedThemes.length > 1) {
     warnOnce(
       'Theme',