From 0cf2fbc6ffa6a8b3a2bd78edb24037f8bbff2f4d Mon Sep 17 00:00:00 2001
From: Marie Lucca <francinelucca@github.com>
Date: Thu, 25 Jun 2026 00:07:13 -0400
Subject: [PATCH 1/3] graduate primer_react_theme_provider_remove_ssr_handoff
 ff

---
 .../src/FeatureFlags/DefaultFeatureFlags.ts   |  1 -
 packages/react/src/ThemeProvider.tsx          | 61 +------------------
 .../src/__tests__/ThemeProvider.test.tsx      | 58 ------------------
 3 files changed, 3 insertions(+), 117 deletions(-)

diff --git a/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts b/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts
index 2b1f5d81a42..763a96df96a 100644
--- a/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts
+++ b/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts
@@ -8,5 +8,4 @@ export const DefaultFeatureFlags = FeatureFlagScope.create({
   primer_react_action_list_group_heading_trailing_action: false,
   primer_react_action_list_item_gap: false,
   primer_react_timeline_list_semantics: false,
-  primer_react_theme_provider_remove_ssr_handoff: false,
 })
diff --git a/packages/react/src/ThemeProvider.tsx b/packages/react/src/ThemeProvider.tsx
index c2876ed7fc5..7c3cb8cf2f7 100644
--- a/packages/react/src/ThemeProvider.tsx
+++ b/packages/react/src/ThemeProvider.tsx
@@ -1,8 +1,6 @@
 import React from 'react'
 import defaultTheme from './theme'
 import deepmerge from 'deepmerge'
-import {useId} from './hooks'
-import {useFeatureFlag} from './FeatureFlags'
 import {useSyncedState} from './hooks/useSyncedState'
 import {ThemeContext} from './ThemeContext'
 import {useTheme} from './useTheme'
@@ -21,7 +19,7 @@ export type ThemeProviderProps = {
   dayScheme?: string
   nightScheme?: string
   /**
-   * No-op when the `primer_react_theme_provider_remove_ssr_handoff` feature flag is enabled.
+   * @deprecated This prop is no longer used and has no effect.
    */
   preventSSRMismatch?: boolean
   /**
@@ -32,33 +30,6 @@ export type ThemeProviderProps = {
   contextOnly?: boolean
 }
 
-// inspired from __NEXT_DATA__, we use application/json to avoid CSRF policy with inline scripts
-const serverHandoffCache = new Map<string, Record<string, unknown>>()
-const emptyHandoff: Record<string, unknown> = {}
-const getServerHandoff = (id: string) => {
-  if (typeof document === 'undefined') return emptyHandoff
-
-  const cached = serverHandoffCache.get(id)
-  if (cached !== undefined) return cached
-
-  try {
-    const serverData = document.getElementById(`__PRIMER_DATA_${id}__`)?.textContent
-    if (serverData) {
-      const parsed = JSON.parse(serverData)
-      serverHandoffCache.set(id, parsed)
-      return parsed
-    }
-  } catch (_error) {
-    // if document/element does not exist or JSON is invalid, suppress error
-  }
-
-  const empty = {}
-  serverHandoffCache.set(id, empty)
-  return empty
-}
-
-const emptySubscribe = () => () => {}
-
 export const ThemeProvider: React.FC<React.PropsWithChildren<ThemeProviderProps>> = ({children, ...props}) => {
   // Get fallback values from parent ThemeProvider (if exists)
   const {
@@ -71,22 +42,11 @@ export const ThemeProvider: React.FC<React.PropsWithChildren<ThemeProviderProps>
   // Initialize state
   const theme = fallbackTheme ?? defaultTheme
 
-  const removeSSRHandoff = useFeatureFlag('primer_react_theme_provider_remove_ssr_handoff')
-  const uniqueDataId = useId()
-
   const [colorMode, setColorMode] = useSyncedState(props.colorMode ?? fallbackColorMode ?? defaultColorMode)
   const [dayScheme, setDayScheme] = useSyncedState(props.dayScheme ?? fallbackDayScheme ?? defaultDayScheme)
   const [nightScheme, setNightScheme] = useSyncedState(props.nightScheme ?? fallbackNightScheme ?? defaultNightScheme)
   const systemColorMode = useSystemColorMode()
-  const clientColorMode = resolveColorMode(colorMode, systemColorMode)
-  // During SSR/hydration, use the server-rendered color mode from the handoff script tag
-  // to avoid mismatches. After hydration, resolve from client state.
-  const ssrResolvedColorMode = React.useSyncExternalStore(
-    emptySubscribe,
-    () => clientColorMode,
-    () => getServerHandoff(uniqueDataId).resolvedServerColorMode ?? clientColorMode,
-  )
-  const resolvedColorMode = removeSSRHandoff ? clientColorMode : ssrResolvedColorMode
+  const resolvedColorMode = resolveColorMode(colorMode, systemColorMode)
   const colorScheme = chooseColorScheme(resolvedColorMode, dayScheme, nightScheme)
   const {resolvedTheme, resolvedColorScheme} = React.useMemo(
     () => applyColorScheme(theme, colorScheme),
@@ -120,22 +80,8 @@ export const ThemeProvider: React.FC<React.PropsWithChildren<ThemeProviderProps>
     ],
   )
 
-  const ssrHandoffScript =
-    !removeSSRHandoff && props.preventSSRMismatch ? (
-      <script
-        type="application/json"
-        id={`__PRIMER_DATA_${uniqueDataId}__`}
-        dangerouslySetInnerHTML={{__html: JSON.stringify({resolvedServerColorMode: resolvedColorMode})}}
-      />
-    ) : null
-
   if (props.contextOnly) {
-    return (
-      <ThemeContext.Provider value={contextValue}>
-        {children}
-        {ssrHandoffScript}
-      </ThemeContext.Provider>
-    )
+    return <ThemeContext.Provider value={contextValue}>{children}</ThemeContext.Provider>
   }
 
   return (
@@ -146,7 +92,6 @@ export const ThemeProvider: React.FC<React.PropsWithChildren<ThemeProviderProps>
         data-dark-theme={nightScheme}
       >
         {children}
-        {ssrHandoffScript}
       </div>
     </ThemeContext.Provider>
   )
diff --git a/packages/react/src/__tests__/ThemeProvider.test.tsx b/packages/react/src/__tests__/ThemeProvider.test.tsx
index 0e46d975ad4..3735ad52e22 100644
--- a/packages/react/src/__tests__/ThemeProvider.test.tsx
+++ b/packages/react/src/__tests__/ThemeProvider.test.tsx
@@ -3,7 +3,6 @@ import userEvent from '@testing-library/user-event'
 import {describe, expect, it, vi} from 'vitest'
 import React from 'react'
 import ThemeProvider from '../ThemeProvider'
-import {FeatureFlags} from '../FeatureFlags'
 import {useColorSchemeVar, useTheme} from '../useTheme'
 
 // copied from '@primer/primitives/dist/css/functional/themes/';
@@ -571,61 +570,4 @@ describe('contextOnly', () => {
 
     expect(screen.getByTestId('consumer').textContent).toBe('night-light-dark_dimmed')
   })
-
-  it('renders the preventSSRMismatch script tag when contextOnly and preventSSRMismatch are both true', () => {
-    const {container} = render(
-      <ThemeProvider contextOnly preventSSRMismatch>
-        <span>Hello</span>
-      </ThemeProvider>,
-    )
-
-    const div = container.querySelector('[data-color-mode]')
-    expect(div).not.toBeInTheDocument()
-
-    const script = container.querySelector('script[type="application/json"]')
-    expect(script).toBeInTheDocument()
-    expect(script?.textContent).toContain('resolvedServerColorMode')
-  })
-})
-
-describe('primer_react_theme_provider_remove_ssr_handoff feature flag', () => {
-  it('does not render the script tag when the feature flag is enabled', () => {
-    const {container} = render(
-      <FeatureFlags flags={{primer_react_theme_provider_remove_ssr_handoff: true}}>
-        <ThemeProvider preventSSRMismatch>
-          <span>Hello</span>
-        </ThemeProvider>
-      </FeatureFlags>,
-    )
-
-    const script = container.querySelector('script[type="application/json"]')
-    expect(script).not.toBeInTheDocument()
-  })
-
-  it('does not render the script tag when the feature flag is enabled and contextOnly is true', () => {
-    const {container} = render(
-      <FeatureFlags flags={{primer_react_theme_provider_remove_ssr_handoff: true}}>
-        <ThemeProvider contextOnly preventSSRMismatch>
-          <span>Hello</span>
-        </ThemeProvider>
-      </FeatureFlags>,
-    )
-
-    const script = container.querySelector('script[type="application/json"]')
-    expect(script).not.toBeInTheDocument()
-  })
-
-  it('renders the script tag when the feature flag is disabled', () => {
-    const {container} = render(
-      <FeatureFlags flags={{primer_react_theme_provider_remove_ssr_handoff: false}}>
-        <ThemeProvider preventSSRMismatch>
-          <span>Hello</span>
-        </ThemeProvider>
-      </FeatureFlags>,
-    )
-
-    const script = container.querySelector('script[type="application/json"]')
-    expect(script).toBeInTheDocument()
-    expect(script?.textContent).toContain('resolvedServerColorMode')
-  })
 })

From 73283f7ac8d72eb0c1f743d397840ea9bd692477 Mon Sep 17 00:00:00 2001
From: Marie Lucca <francinelucca@github.com>
Date: Thu, 25 Jun 2026 00:12:01 -0400
Subject: [PATCH 2/3] add changeset

---
 .changeset/graduate-theming-feature-flags.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/graduate-theming-feature-flags.md

diff --git a/.changeset/graduate-theming-feature-flags.md b/.changeset/graduate-theming-feature-flags.md
new file mode 100644
index 00000000000..6d9996d063d
--- /dev/null
+++ b/.changeset/graduate-theming-feature-flags.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+ThemeProvider: Remove `primer_react_theme_provider_remove_ssr_handoff` feature flag.
\ No newline at end of file

From fda08a3d78e71a316eba8dca8d2ebe75e431f52b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 25 Jun 2026 04:22:39 +0000
Subject: [PATCH 3/3] Update useTheme hook docs for deprecated
 preventSSRMismatch

Co-authored-by: francinelucca <40550942+francinelucca@users.noreply.github.com>
---
 packages/react/src/utils/useTheme.hookDocs.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/utils/useTheme.hookDocs.json b/packages/react/src/utils/useTheme.hookDocs.json
index 8ac86ce7ead..12636ab100d 100644
--- a/packages/react/src/utils/useTheme.hookDocs.json
+++ b/packages/react/src/utils/useTheme.hookDocs.json
@@ -33,7 +33,7 @@
         {
           "name": "preventSSRMismatch",
           "type": "boolean",
-          "description": "Prevent SSR mismatch by injecting server-side color mode."
+          "description": "Deprecated: This prop is no longer used and has no effect."
         }
       ]
     },