From 1a8ef652e6e7f383ce9b1294b90270e51535a3c2 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 13:36:46 +0200
Subject: [PATCH 01/16] tmp

---
 examples/nextjs/src/app/layout.tsx            |   3 +-
 packages/react/src/ThemeProvider.tsx          |   3 +
 packages/react/src/index.ts                   |   2 +
 .../src/components/ThemeProvider.tsx          | 243 ++++++++++++++++++
 4 files changed, 250 insertions(+), 1 deletion(-)
 create mode 100644 packages/styled-react/src/components/ThemeProvider.tsx

diff --git a/examples/nextjs/src/app/layout.tsx b/examples/nextjs/src/app/layout.tsx
index ec8ff0f19a7..d193b551f09 100644
--- a/examples/nextjs/src/app/layout.tsx
+++ b/examples/nextjs/src/app/layout.tsx
@@ -1,5 +1,6 @@
 import './global.css'
-import {BaseStyles, ThemeProvider} from '@primer/react'
+import {ThemeProvider} from '@primer/styled-react'
+import {BaseStyles} from '@primer/react'
 import {StyledComponentsRegistry} from './registry'
 
 export const metadata = {
diff --git a/packages/react/src/ThemeProvider.tsx b/packages/react/src/ThemeProvider.tsx
index 416e317a540..91d045b2168 100644
--- a/packages/react/src/ThemeProvider.tsx
+++ b/packages/react/src/ThemeProvider.tsx
@@ -105,6 +105,8 @@ export const ThemeProvider: React.FC<React.PropsWithChildren<ThemeProviderProps>
     [colorMode, systemColorMode, setColorMode],
   )
 
+  console.log({resolvedTheme})
+
   return (
     <ThemeContext.Provider
       value={{
@@ -217,6 +219,7 @@ function applyColorScheme(
   theme: Theme,
   colorScheme: string,
 ): {resolvedTheme: Theme; resolvedColorScheme: string | undefined} {
+  console.log({theme, colorScheme})
   if (!theme.colorSchemes) {
     return {
       resolvedTheme: theme,
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index f37dbea38d8..f4fc3fa7669 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -46,6 +46,8 @@ export {useResizeObserver} from './hooks/useResizeObserver'
 export {useResponsiveValue, type ResponsiveValue} from './hooks/useResponsiveValue'
 export {default as useIsomorphicLayoutEffect} from './utils/useIsomorphicLayoutEffect'
 export {useProvidedRefOrCreate} from './hooks/useProvidedRefOrCreate'
+export {useId} from './hooks/useId'
+export {useSyncedState} from './hooks/useSyncedState'
 
 // Utils
 export {createComponent} from './utils/create-component'
diff --git a/packages/styled-react/src/components/ThemeProvider.tsx b/packages/styled-react/src/components/ThemeProvider.tsx
new file mode 100644
index 00000000000..adea1055ebf
--- /dev/null
+++ b/packages/styled-react/src/components/ThemeProvider.tsx
@@ -0,0 +1,243 @@
+import React from 'react'
+import ReactDOM from 'react-dom'
+import {ThemeProvider as SCThemeProvider} from 'styled-components'
+import {theme as defaultTheme, useId, useSyncedState} from '@primer/react'
+import deepmerge from 'deepmerge'
+
+export const defaultColorMode = 'day'
+const defaultDayScheme = 'light'
+const defaultNightScheme = 'dark'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Theme = {[key: string]: any}
+type ColorMode = 'day' | 'night' | 'light' | 'dark'
+export type ColorModeWithAuto = ColorMode | 'auto'
+
+export type ThemeProviderProps = {
+  theme?: Theme
+  colorMode?: ColorModeWithAuto
+  dayScheme?: string
+  nightScheme?: string
+  preventSSRMismatch?: boolean
+}
+
+const ThemeContext = React.createContext<{
+  theme?: Theme
+  colorScheme?: string
+  colorMode?: ColorModeWithAuto
+  resolvedColorMode?: ColorMode
+  resolvedColorScheme?: string
+  dayScheme?: string
+  nightScheme?: string
+  setColorMode: React.Dispatch<React.SetStateAction<ColorModeWithAuto>>
+  setDayScheme: React.Dispatch<React.SetStateAction<string>>
+  setNightScheme: React.Dispatch<React.SetStateAction<string>>
+}>({
+  setColorMode: () => null,
+  setDayScheme: () => null,
+  setNightScheme: () => null,
+})
+
+// inspired from __NEXT_DATA__, we use application/json to avoid CSRF policy with inline scripts
+const getServerHandoff = (id: string) => {
+  try {
+    const serverData = document.getElementById(`__PRIMER_DATA_${id}__`)?.textContent
+    if (serverData) return JSON.parse(serverData)
+  } catch (_error) {
+    // if document/element does not exist or JSON is invalid, supress error
+  }
+  return {}
+}
+
+export const ThemeProvider: React.FC<React.PropsWithChildren<ThemeProviderProps>> = ({children, ...props}) => {
+  // Get fallback values from parent ThemeProvider (if exists)
+  const {
+    theme: fallbackTheme,
+    colorMode: fallbackColorMode,
+    dayScheme: fallbackDayScheme,
+    nightScheme: fallbackNightScheme,
+  } = useTheme()
+
+  // Initialize state
+  const theme = props.theme ?? fallbackTheme ?? defaultTheme
+
+  const uniqueDataId = useId()
+  const {resolvedServerColorMode} = getServerHandoff(uniqueDataId)
+  const resolvedColorModePassthrough = React.useRef(resolvedServerColorMode)
+
+  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 resolvedColorMode = resolvedColorModePassthrough.current || resolveColorMode(colorMode, systemColorMode)
+  const colorScheme = chooseColorScheme(resolvedColorMode, dayScheme, nightScheme)
+  const {resolvedTheme, resolvedColorScheme} = React.useMemo(
+    () => applyColorScheme(theme, colorScheme),
+    [theme, colorScheme],
+  )
+
+  // this effect will only run on client
+  React.useEffect(
+    function updateColorModeAfterServerPassthrough() {
+      const resolvedColorModeOnClient = resolveColorMode(colorMode, systemColorMode)
+
+      if (resolvedColorModePassthrough.current) {
+        // if the resolved color mode passed on from the server is not the resolved color mode on client, change it!
+        if (resolvedColorModePassthrough.current !== resolvedColorModeOnClient) {
+          window.setTimeout(() => {
+            // use ReactDOM.flushSync to prevent automatic batching of state updates since React 18
+            // ref: https://github.com/reactwg/react-18/discussions/21
+            ReactDOM.flushSync(() => {
+              // override colorMode to whatever is resolved on the client to get a re-render
+              setColorMode(resolvedColorModeOnClient)
+            })
+
+            // immediately after that, set the colorMode to what the user passed to respond to system color mode changes
+            setColorMode(colorMode)
+          })
+        }
+
+        resolvedColorModePassthrough.current = null
+      }
+    },
+    [colorMode, systemColorMode, setColorMode],
+  )
+
+  return (
+    <ThemeContext.Provider
+      value={{
+        theme: resolvedTheme,
+        colorScheme,
+        colorMode,
+        resolvedColorMode,
+        resolvedColorScheme,
+        dayScheme,
+        nightScheme,
+        setColorMode,
+        setDayScheme,
+        setNightScheme,
+      }}
+    >
+      <SCThemeProvider theme={resolvedTheme}>
+        {children}
+        {props.preventSSRMismatch ? (
+          <script
+            type="application/json"
+            id={`__PRIMER_DATA_${uniqueDataId}__`}
+            dangerouslySetInnerHTML={{__html: JSON.stringify({resolvedServerColorMode: resolvedColorMode})}}
+          />
+        ) : null}
+      </SCThemeProvider>
+    </ThemeContext.Provider>
+  )
+}
+
+export function useTheme() {
+  return React.useContext(ThemeContext)
+}
+
+export function useColorSchemeVar(values: Partial<Record<string, string>>, fallback: string) {
+  const {colorScheme = ''} = useTheme()
+  return values[colorScheme] ?? fallback
+}
+
+function useSystemColorMode() {
+  const [systemColorMode, setSystemColorMode] = React.useState(getSystemColorMode)
+
+  React.useEffect(() => {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const media = window?.matchMedia?.('(prefers-color-scheme: dark)')
+
+    function matchesMediaToColorMode(matches: boolean) {
+      return matches ? 'night' : 'day'
+    }
+
+    function handleChange(event: MediaQueryListEvent) {
+      const isNight = event.matches
+      setSystemColorMode(matchesMediaToColorMode(isNight))
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (media) {
+      // just in case the preference changed before the event listener was attached
+      const isNight = media.matches
+      setSystemColorMode(matchesMediaToColorMode(isNight))
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (media.addEventListener !== undefined) {
+        media.addEventListener('change', handleChange)
+        return function cleanup() {
+          media.removeEventListener('change', handleChange)
+        }
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      else if (media.addListener !== undefined) {
+        media.addListener(handleChange)
+        return function cleanup() {
+          media.removeListener(handleChange)
+        }
+      }
+    }
+  }, [])
+
+  return systemColorMode
+}
+
+function getSystemColorMode(): ColorMode {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (typeof window !== 'undefined' && window.matchMedia?.('(prefers-color-scheme: dark)')?.matches) {
+    return 'night'
+  }
+
+  return 'day'
+}
+
+function resolveColorMode(colorMode: ColorModeWithAuto, systemColorMode: ColorMode) {
+  switch (colorMode) {
+    case 'auto':
+      return systemColorMode
+    default:
+      return colorMode
+  }
+}
+
+function chooseColorScheme(colorMode: ColorMode, dayScheme: string, nightScheme: string) {
+  switch (colorMode) {
+    case 'day':
+    case 'light':
+      return dayScheme
+    case 'dark':
+    case 'night':
+      return nightScheme
+  }
+}
+
+function applyColorScheme(
+  theme: Theme,
+  colorScheme: string,
+): {resolvedTheme: Theme; resolvedColorScheme: string | undefined} {
+  if (!theme.colorSchemes) {
+    return {
+      resolvedTheme: theme,
+      resolvedColorScheme: undefined,
+    }
+  }
+
+  if (!theme.colorSchemes[colorScheme]) {
+    // eslint-disable-next-line no-console
+    console.error(`\`${colorScheme}\` scheme not defined in \`theme.colorSchemes\``)
+
+    // Apply the first defined color scheme
+    const defaultColorScheme = Object.keys(theme.colorSchemes)[0]
+    return {
+      resolvedTheme: deepmerge(theme, theme.colorSchemes[defaultColorScheme]),
+      resolvedColorScheme: defaultColorScheme,
+    }
+  }
+
+  return {
+    resolvedTheme: deepmerge(theme, theme.colorSchemes[colorScheme]),
+    resolvedColorScheme: colorScheme,
+  }
+}
+
+export default ThemeProvider

From c3476b50713a140710367ecf07620d9eaa09d7b5 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 15:15:18 +0200
Subject: [PATCH 02/16] add base styles to styled-react

---
 .../src/components/BaseStyles.tsx             | 149 ++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 packages/styled-react/src/components/BaseStyles.tsx

diff --git a/packages/styled-react/src/components/BaseStyles.tsx b/packages/styled-react/src/components/BaseStyles.tsx
new file mode 100644
index 00000000000..faf1b389297
--- /dev/null
+++ b/packages/styled-react/src/components/BaseStyles.tsx
@@ -0,0 +1,149 @@
+import type React from 'react'
+import {type CSSProperties, type PropsWithChildren} from 'react'
+import * as styledSystem from 'styled-system'
+import {useTheme} from './ThemeProvider'
+
+import 'focus-visible'
+import {createGlobalStyle} from 'styled-components'
+
+export interface SystemCommonProps
+  extends styledSystem.ColorProps,
+    styledSystem.SpaceProps,
+    styledSystem.DisplayProps {}
+
+export interface SystemTypographyProps extends styledSystem.TypographyProps {
+  whiteSpace?: 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line'
+}
+
+const GlobalStyle = createGlobalStyle<{colorScheme?: 'light' | 'dark'}>`
+  * {
+    box-sizing: border-box;
+  }
+
+  body {
+    margin: 0;
+  }
+
+  table {
+    /* stylelint-disable-next-line primer/borders */
+    border-collapse: collapse;
+  }
+
+  [data-color-mode='light'] input {
+    color-scheme: light;
+  }
+
+  [data-color-mode='dark'] input {
+    color-scheme: dark;
+  }
+
+  @media (prefers-color-scheme: light) {
+    [data-color-mode='auto'][data-light-theme*='light'] {
+      color-scheme: light;
+    }
+  }
+
+  @media (prefers-color-scheme: dark) {
+    [data-color-mode='auto'][data-dark-theme*='dark'] {
+      color-scheme: dark;
+    }
+  }
+
+  [role='button']:focus:not(:focus-visible):not(:global(.focus-visible)),
+  [role='tabpanel'][tabindex='0']:focus:not(:focus-visible):not(:global(.focus-visible)),
+  button:focus:not(:focus-visible):not(:global(.focus-visible)),
+  summary:focus:not(:focus-visible):not(:global(.focus-visible)),
+  a:focus:not(:focus-visible):not(:global(.focus-visible)) {
+    outline: none;
+    box-shadow: none;
+  }
+
+  [tabindex='0']:focus:not(:focus-visible):not(:global(.focus-visible)),
+  details-dialog:focus:not(:focus-visible):not(:global(.focus-visible)) {
+    outline: none;
+  }
+
+  /* -------------------------------------------------------------------------- */
+
+  .BaseStyles {
+    font-family: var(--BaseStyles-fontFamily, var(--fontStack-system));
+    /* stylelint-disable-next-line primer/typography */
+    line-height: var(--BaseStyles-lineHeight, 1.5);
+    /* stylelint-disable-next-line primer/colors */
+    color: var(--BaseStyles-fgColor, var(--fgColor-default));
+
+    /* Global styles for light mode */
+    &:has([data-color-mode='light']) {
+      input & {
+        color-scheme: light;
+      }
+    }
+
+    /* Global styles for dark mode */
+    &:has([data-color-mode='dark']) {
+      input & {
+        color-scheme: dark;
+      }
+    }
+
+    /* Low-specificity default link styling */
+    :where(a:not([class*='prc-']):not([class*='PRC-']):not([class*='Primer_Brand__'])) {
+      color: var(--fgColor-accent, var(--color-accent-fg));
+      text-decoration: none;
+
+      &:hover {
+        text-decoration: underline;
+      }
+    }
+  }
+`
+
+export type BaseStylesProps = PropsWithChildren & {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  as?: React.ComponentType<any> | keyof JSX.IntrinsicElements
+  className?: string
+  style?: CSSProperties
+  color?: string // Fixes `color` ts-error
+} & SystemTypographyProps &
+  SystemCommonProps
+
+export function BaseStyles({
+  children,
+  color,
+  fontFamily,
+  lineHeight,
+  className,
+  as: Component = 'div',
+  style,
+  ...rest
+}: BaseStylesProps) {
+  const {colorMode, colorScheme, dayScheme, nightScheme} = useTheme()
+
+  const baseStyles = {
+    ['--BaseStyles-fgColor']: color,
+    ['--BaseStyles-fontFamily']: fontFamily,
+    ['--BaseStyles-lineHeight']: lineHeight,
+  }
+
+  return (
+    <Component
+      data-portal-root
+      /**
+       * We need to map valid primer/react color modes onto valid color modes for primer/primitives
+       * valid color modes for primer/primitives: auto | light | dark
+       * valid color modes for primer/primer: auto | day | night | light | dark
+       */
+      data-color-mode={colorMode === 'auto' ? 'auto' : colorScheme?.includes('dark') ? 'dark' : 'light'}
+      data-light-theme={dayScheme}
+      data-dark-theme={nightScheme}
+      style={{
+        ...baseStyles,
+        ...style,
+      }}
+      {...rest}
+    >
+      <GlobalStyle colorScheme={colorScheme?.includes('dark') ? 'dark' : 'light'} />
+      {children}
+    </Component>
+  )
+}

From a60f6f205a2e30bdb5b03df9aef8bb7712772af4 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 15:15:29 +0200
Subject: [PATCH 03/16] export themeprovider and basestyles

---
 packages/styled-react/src/index.tsx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/styled-react/src/index.tsx b/packages/styled-react/src/index.tsx
index 70aafe530fb..b6fe09fd7e7 100644
--- a/packages/styled-react/src/index.tsx
+++ b/packages/styled-react/src/index.tsx
@@ -10,7 +10,8 @@ export {TextInput} from '@primer/react'
 export {type TextInputProps} from '@primer/react'
 
 // theming depends on styled-components
-export {ThemeProvider} from '@primer/react'
+export {ThemeProvider} from './components/ThemeProvider'
+export {BaseStyles} from './components/BaseStyles'
 export {merge} from '@primer/react'
 export {theme} from '@primer/react'
 export {themeGet} from '@primer/react'

From 103ab98e11ee7a4e1d99b467d5e7ee2133d65507 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 15:15:46 +0200
Subject: [PATCH 04/16] next example uses styled-react

---
 examples/nextjs/src/app/layout.tsx |  3 +--
 examples/nextjs/src/app/page.tsx   | 22 ++++++++++++++++++++--
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/examples/nextjs/src/app/layout.tsx b/examples/nextjs/src/app/layout.tsx
index d193b551f09..8e845a6afba 100644
--- a/examples/nextjs/src/app/layout.tsx
+++ b/examples/nextjs/src/app/layout.tsx
@@ -1,6 +1,5 @@
 import './global.css'
-import {ThemeProvider} from '@primer/styled-react'
-import {BaseStyles} from '@primer/react'
+import {ThemeProvider, BaseStyles} from '@primer/styled-react'
 import {StyledComponentsRegistry} from './registry'
 
 export const metadata = {
diff --git a/examples/nextjs/src/app/page.tsx b/examples/nextjs/src/app/page.tsx
index 7b9ad9f2e0d..a5ff1b4349e 100644
--- a/examples/nextjs/src/app/page.tsx
+++ b/examples/nextjs/src/app/page.tsx
@@ -1,5 +1,23 @@
-import {Button} from '@primer/react'
+'use client'
+
+import {Button, Stack, Box} from '@primer/react'
+import styled from 'styled-components'
+
+const StyledDiv = styled.div(({theme}) => {
+  return {
+    padding: theme.space[5],
+    backgroundColor: theme.colors.btn.primary.bg,
+  }
+})
 
 export default function IndexPage() {
-  return <Button>Hello world</Button>
+  return (
+    <Stack direction="horizontal">
+      <Button variant="primary" sx={{padding: 5}}>
+        Hello world
+      </Button>
+      <Box sx={{padding: 5, backgroundColor: 'btn.primary.bg'}}>Hello world</Box>
+      <StyledDiv>Hello world</StyledDiv>
+    </Stack>
+  )
 }

From 64374f54f5c1522eadaf4b45b89f5e003b90450f Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 15:59:57 +0200
Subject: [PATCH 05/16] add use client like primer/react

---
 packages/styled-react/rollup.config.js | 104 +++++++++++++++++++++++++
 packages/styled-react/src/index.tsx    |   2 +
 2 files changed, 106 insertions(+)

diff --git a/packages/styled-react/rollup.config.js b/packages/styled-react/rollup.config.js
index 8aae93d5045..fdae02031ac 100644
--- a/packages/styled-react/rollup.config.js
+++ b/packages/styled-react/rollup.config.js
@@ -2,6 +2,7 @@ import babel from '@rollup/plugin-babel'
 import {defineConfig} from 'rollup'
 import typescript from 'rollup-plugin-typescript2'
 import packageJson from './package.json' with {type: 'json'}
+import MagicString from 'magic-string'
 
 const dependencies = [
   ...Object.keys(packageJson.peerDependencies ?? {}),
@@ -26,9 +27,112 @@ export default defineConfig({
       extensions: ['.ts', '.tsx'],
       babelHelpers: 'bundled',
     }),
+    /**
+     * This custom rollup plugin allows us to preserve directives in source
+     * code, such as "use client", in order to support React Server Components.
+     *
+     * The source for this plugin is inspired by:
+     * https://github.com/Ephem/rollup-plugin-preserve-directives
+     */
+    {
+      name: 'preserve-directives',
+      transform(code) {
+        const ast = this.parse(code)
+        if (ast.type !== 'Program' || !ast.body) {
+          return {
+            code,
+            ast,
+            map: null,
+          }
+        }
+
+        let hasClientDirective = false
+
+        for (const node of ast.body) {
+          if (!node) {
+            continue
+          }
+
+          if (node.type !== 'ExpressionStatement') {
+            continue
+          }
+
+          if (node.directive === 'use client') {
+            hasClientDirective = true
+            break
+          }
+        }
+
+        if (hasClientDirective) {
+          return {
+            code,
+            ast,
+            map: null,
+            meta: {
+              hasClientDirective: true,
+            },
+          }
+        }
+
+        return {
+          code,
+          ast,
+          map: null,
+        }
+      },
+      renderChunk: {
+        order: 'post',
+        handler(code, chunk, options) {
+          // If `preserveModules` is not set to true, we can't be sure if the client
+          // directive corresponds to the whole chunk or just a part of it.
+          if (!options.preserveModules) {
+            return undefined
+          }
+
+          let chunkHasClientDirective = false
+
+          for (const moduleId of Object.keys(chunk.modules)) {
+            const hasClientDirective = this.getModuleInfo(moduleId)?.meta?.hasClientDirective
+            if (hasClientDirective) {
+              chunkHasClientDirective = true
+              break
+            }
+          }
+
+          if (chunkHasClientDirective) {
+            console.log('huuuuu')
+            const transformed = new MagicString(code)
+            transformed.prepend(`"use client";\n`)
+            const sourcemap = transformed.generateMap({
+              includeContent: true,
+            })
+            return {
+              code: transformed.toString(),
+              map: sourcemap,
+            }
+          }
+
+          return null
+        },
+      },
+    },
   ],
+  onwarn(warning, defaultHandler) {
+    // Dependencies or modules may use "use client" as an indicator for React
+    // Server Components that this module should only be loaded on the client.
+    if (warning.code === 'MODULE_LEVEL_DIRECTIVE' && warning.message.includes('use client')) {
+      return
+    }
+
+    if (warning.code === 'CIRCULAR_DEPENDENCY') {
+      throw warning
+    }
+
+    defaultHandler(warning)
+  },
   output: {
     dir: 'dist',
     format: 'esm',
+    preserveModules: true,
   },
 })
diff --git a/packages/styled-react/src/index.tsx b/packages/styled-react/src/index.tsx
index b6fe09fd7e7..7a00f24d663 100644
--- a/packages/styled-react/src/index.tsx
+++ b/packages/styled-react/src/index.tsx
@@ -1,3 +1,5 @@
+'use client'
+
 export {Box, type BoxProps} from './components/Box'
 export {Button} from '@primer/react'
 export {Details} from '@primer/react'

From ff23c051edb9f98d34dcf3beac8971e06b8a7317 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 16:00:58 +0200
Subject: [PATCH 06/16] missed the classname!

---
 packages/styled-react/src/components/BaseStyles.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/styled-react/src/components/BaseStyles.tsx b/packages/styled-react/src/components/BaseStyles.tsx
index faf1b389297..1a5ae83d3fe 100644
--- a/packages/styled-react/src/components/BaseStyles.tsx
+++ b/packages/styled-react/src/components/BaseStyles.tsx
@@ -127,6 +127,7 @@ export function BaseStyles({
 
   return (
     <Component
+      className="BaseStyles"
       data-portal-root
       /**
        * We need to map valid primer/react color modes onto valid color modes for primer/primitives

From c92a752dca908fa175ceb367e305990c297962d7 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 22:27:13 +0200
Subject: [PATCH 07/16] missed couple things

---
 packages/react/src/ThemeProvider.tsx                | 3 ---
 packages/styled-react/rollup.config.js              | 1 -
 packages/styled-react/src/components/BaseStyles.tsx | 4 +++-
 3 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/ThemeProvider.tsx b/packages/react/src/ThemeProvider.tsx
index 91d045b2168..416e317a540 100644
--- a/packages/react/src/ThemeProvider.tsx
+++ b/packages/react/src/ThemeProvider.tsx
@@ -105,8 +105,6 @@ export const ThemeProvider: React.FC<React.PropsWithChildren<ThemeProviderProps>
     [colorMode, systemColorMode, setColorMode],
   )
 
-  console.log({resolvedTheme})
-
   return (
     <ThemeContext.Provider
       value={{
@@ -219,7 +217,6 @@ function applyColorScheme(
   theme: Theme,
   colorScheme: string,
 ): {resolvedTheme: Theme; resolvedColorScheme: string | undefined} {
-  console.log({theme, colorScheme})
   if (!theme.colorSchemes) {
     return {
       resolvedTheme: theme,
diff --git a/packages/styled-react/rollup.config.js b/packages/styled-react/rollup.config.js
index fdae02031ac..60091798713 100644
--- a/packages/styled-react/rollup.config.js
+++ b/packages/styled-react/rollup.config.js
@@ -100,7 +100,6 @@ export default defineConfig({
           }
 
           if (chunkHasClientDirective) {
-            console.log('huuuuu')
             const transformed = new MagicString(code)
             transformed.prepend(`"use client";\n`)
             const sourcemap = transformed.generateMap({
diff --git a/packages/styled-react/src/components/BaseStyles.tsx b/packages/styled-react/src/components/BaseStyles.tsx
index 1a5ae83d3fe..ef23b49d263 100644
--- a/packages/styled-react/src/components/BaseStyles.tsx
+++ b/packages/styled-react/src/components/BaseStyles.tsx
@@ -1,5 +1,7 @@
 import type React from 'react'
 import {type CSSProperties, type PropsWithChildren} from 'react'
+import {clsx} from 'clsx'
+// eslint-disable-next-line import/no-namespace
 import * as styledSystem from 'styled-system'
 import {useTheme} from './ThemeProvider'
 
@@ -127,7 +129,7 @@ export function BaseStyles({
 
   return (
     <Component
-      className="BaseStyles"
+      className={clsx('BaseStyles', className)}
       data-portal-root
       /**
        * We need to map valid primer/react color modes onto valid color modes for primer/primitives

From 15bda3576ad659a29ddb15382061bd7bf7705125 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 22:28:58 +0200
Subject: [PATCH 08/16] update exports snapshot

---
 .../src/__tests__/__snapshots__/exports.test.ts.snap             | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/styled-react/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/styled-react/src/__tests__/__snapshots__/exports.test.ts.snap
index 8c3a1edd8d6..f6787b86d27 100644
--- a/packages/styled-react/src/__tests__/__snapshots__/exports.test.ts.snap
+++ b/packages/styled-react/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -6,6 +6,7 @@ exports[`@primer/styled-react exports 1`] = `
   "ActionMenu",
   "Autocomplete",
   "Avatar",
+  "BaseStyles",
   "Box",
   "Breadcrumb",
   "Breadcrumbs",

From d7da338c4fc85874ead920b1e5e89b0af7efd1a6 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 22:30:10 +0200
Subject: [PATCH 09/16] install styled-react as example dependency

---
 examples/nextjs/package.json |  1 +
 package-lock.json            | 15 ++++++++-------
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/examples/nextjs/package.json b/examples/nextjs/package.json
index 1b00a81577c..046802f1680 100644
--- a/examples/nextjs/package.json
+++ b/examples/nextjs/package.json
@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "@primer/react": "38.0.0-rc.5",
+    "@primer/styled-react": "1.0.0-rc.5",
     "next": "^15.2.3",
     "react": "18.3.1",
     "react-dom": "18.3.1",
diff --git a/package-lock.json b/package-lock.json
index 67271ec9dae..7ce45bb7e50 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -75,7 +75,7 @@
         "react-dom": "^18.3.1"
       },
       "devDependencies": {
-        "@primer/react": "38.0.0-rc.4",
+        "@primer/react": "38.0.0-rc.5",
         "@types/react": "^18.3.11",
         "@types/react-dom": "^18.3.0",
         "@vitejs/plugin-react": "^4.3.3",
@@ -88,7 +88,8 @@
       "name": "example-nextjs",
       "version": "0.0.0",
       "dependencies": {
-        "@primer/react": "38.0.0-rc.4",
+        "@primer/react": "38.0.0-rc.5",
+        "@primer/styled-react": "1.0.0-rc.5",
         "next": "^15.2.3",
         "react": "18.3.1",
         "react-dom": "18.3.1",
@@ -104,7 +105,7 @@
       "version": "0.0.0",
       "dependencies": {
         "@primer/octicons-react": "^19.14.0",
-        "@primer/react": "38.0.0-rc.4",
+        "@primer/react": "38.0.0-rc.5",
         "clsx": "^2.1.1",
         "next": "^15.2.3",
         "react": "18.3.1",
@@ -26316,7 +26317,7 @@
     },
     "packages/react": {
       "name": "@primer/react",
-      "version": "38.0.0-rc.4",
+      "version": "38.0.0-rc.5",
       "license": "MIT",
       "dependencies": {
         "@github/mini-throttle": "^2.1.1",
@@ -26893,11 +26894,11 @@
     },
     "packages/styled-react": {
       "name": "@primer/styled-react",
-      "version": "1.0.0-rc.4",
+      "version": "1.0.0-rc.5",
       "devDependencies": {
         "@babel/preset-react": "^7.27.1",
         "@babel/preset-typescript": "^7.27.1",
-        "@primer/react": "^38.0.0-rc.4",
+        "@primer/react": "^38.0.0-rc.5",
         "@rollup/plugin-babel": "^6.0.4",
         "@types/react": "18.3.11",
         "@types/react-dom": "18.3.1",
@@ -26913,7 +26914,7 @@
         "typescript": "^5.9.2"
       },
       "peerDependencies": {
-        "@primer/react": "38.0.0-rc.4",
+        "@primer/react": "38.0.0-rc.5",
         "@types/react": "18.x || 19.x",
         "@types/react-dom": "18.x || 19.x",
         "@types/react-is": "18.x || 19.x",

From cc49f5e12938986b71376e205daa60bc42ee5363 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 23:10:53 +0200
Subject: [PATCH 10/16] fix lint + test

---
 packages/react/src/__tests__/__snapshots__/exports.test.ts.snap | 2 ++
 packages/styled-react/src/components/BaseStyles.tsx             | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
index 6a9e1c692f9..4057c681ce2 100644
--- a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
+++ b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -214,6 +214,7 @@ exports[`@primer/react > should not update exports without a semver change 1`] =
   "useFocusTrap",
   "useFocusZone",
   "useFormControlForwardedProps",
+  "useId",
   "useIsomorphicLayoutEffect",
   "useOnEscapePress",
   "useOnOutsideClick",
@@ -224,6 +225,7 @@ exports[`@primer/react > should not update exports without a semver change 1`] =
   "useResizeObserver",
   "useResponsiveValue",
   "useSafeTimeout",
+  "useSyncedState",
   "useTheme",
   "VisuallyHidden",
   "type VisuallyHiddenProps",
diff --git a/packages/styled-react/src/components/BaseStyles.tsx b/packages/styled-react/src/components/BaseStyles.tsx
index ef23b49d263..e58f33100e8 100644
--- a/packages/styled-react/src/components/BaseStyles.tsx
+++ b/packages/styled-react/src/components/BaseStyles.tsx
@@ -2,7 +2,7 @@ import type React from 'react'
 import {type CSSProperties, type PropsWithChildren} from 'react'
 import {clsx} from 'clsx'
 // eslint-disable-next-line import/no-namespace
-import * as styledSystem from 'styled-system'
+import type * as styledSystem from 'styled-system'
 import {useTheme} from './ThemeProvider'
 
 import 'focus-visible'

From 0ad57656f1b065c8901d8126923bdac9749b9744 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Tue, 7 Oct 2025 23:13:59 +0200
Subject: [PATCH 11/16] add changeset

---
 .changeset/styled-react-themeprovider.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 .changeset/styled-react-themeprovider.md

diff --git a/.changeset/styled-react-themeprovider.md b/.changeset/styled-react-themeprovider.md
new file mode 100644
index 00000000000..dc5aa5e0a94
--- /dev/null
+++ b/.changeset/styled-react-themeprovider.md
@@ -0,0 +1,7 @@
+---
+"@primer/react": patch
+"@primer/styled-react": minor
+---
+
+@primer/react: Export `useId` and `useSyncedState`
+@primer/styled-react: Add `ThemeProvider` and `BaseStyles`

From d6d180bb52477ec8a2a8db8cc70eef559097dafd Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Wed, 8 Oct 2025 13:48:07 +0200
Subject: [PATCH 12/16] export local useTheme from styled-react

---
 examples/nextjs/src/app/page.tsx    | 17 +++++++++++++++++
 packages/styled-react/src/index.tsx |  4 +---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/examples/nextjs/src/app/page.tsx b/examples/nextjs/src/app/page.tsx
index a5ff1b4349e..36d8dd9aadc 100644
--- a/examples/nextjs/src/app/page.tsx
+++ b/examples/nextjs/src/app/page.tsx
@@ -1,6 +1,7 @@
 'use client'
 
 import {Button, Stack, Box} from '@primer/react'
+import {useTheme} from '@primer/styled-react'
 import styled from 'styled-components'
 
 const StyledDiv = styled.div(({theme}) => {
@@ -10,6 +11,21 @@ const StyledDiv = styled.div(({theme}) => {
   }
 })
 
+const ThemeUser = props => {
+  const {theme} = useTheme()
+  console.log(theme)
+  return (
+    <div
+      style={{
+        padding: theme?.space[5],
+        backgroundColor: theme?.colors.btn.primary.bg,
+      }}
+    >
+      Hello world
+    </div>
+  )
+}
+
 export default function IndexPage() {
   return (
     <Stack direction="horizontal">
@@ -18,6 +34,7 @@ export default function IndexPage() {
       </Button>
       <Box sx={{padding: 5, backgroundColor: 'btn.primary.bg'}}>Hello world</Box>
       <StyledDiv>Hello world</StyledDiv>
+      <ThemeUser />
     </Stack>
   )
 }
diff --git a/packages/styled-react/src/index.tsx b/packages/styled-react/src/index.tsx
index 7a00f24d663..1f24c641214 100644
--- a/packages/styled-react/src/index.tsx
+++ b/packages/styled-react/src/index.tsx
@@ -12,13 +12,11 @@ export {TextInput} from '@primer/react'
 export {type TextInputProps} from '@primer/react'
 
 // theming depends on styled-components
-export {ThemeProvider} from './components/ThemeProvider'
+export {ThemeProvider, useTheme, useColorSchemeVar} from './components/ThemeProvider'
 export {BaseStyles} from './components/BaseStyles'
 export {merge} from '@primer/react'
 export {theme} from '@primer/react'
 export {themeGet} from '@primer/react'
-export {useColorSchemeVar} from '@primer/react'
-export {useTheme} from '@primer/react'
 
 export {
   ActionList,

From 7d248e8fc797e921943acdb95972e26f0c30f23c Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Wed, 8 Oct 2025 13:53:28 +0200
Subject: [PATCH 13/16] removed unused props

---
 examples/nextjs/src/app/page.tsx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/examples/nextjs/src/app/page.tsx b/examples/nextjs/src/app/page.tsx
index 36d8dd9aadc..4910ebc2e78 100644
--- a/examples/nextjs/src/app/page.tsx
+++ b/examples/nextjs/src/app/page.tsx
@@ -11,9 +11,8 @@ const StyledDiv = styled.div(({theme}) => {
   }
 })
 
-const ThemeUser = props => {
+const ThemeUser = () => {
   const {theme} = useTheme()
-  console.log(theme)
   return (
     <div
       style={{

From 888faadd3bcd02842f21aace7c239f9db26fa187 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Fri, 10 Oct 2025 11:52:00 +0200
Subject: [PATCH 14/16] feature flag the switch

---
 .../src/FeatureFlags/DefaultFeatureFlags.ts   |  1 +
 .../src/components/FeatureFlaggedTheming.tsx  | 49 +++++++++++++++++++
 packages/styled-react/src/index.tsx           |  3 +-
 3 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 packages/styled-react/src/components/FeatureFlaggedTheming.tsx

diff --git a/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts b/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts
index f60c9687834..7a1112d7e37 100644
--- a/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts
+++ b/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts
@@ -8,4 +8,5 @@ export const DefaultFeatureFlags = FeatureFlagScope.create({
   primer_react_select_panel_fullscreen_on_narrow: false,
   primer_react_select_panel_order_selected_at_top: false,
   primer_react_select_panel_remove_active_descendant: false,
+  primer_react_use_styled_react_theming: false,
 })
diff --git a/packages/styled-react/src/components/FeatureFlaggedTheming.tsx b/packages/styled-react/src/components/FeatureFlaggedTheming.tsx
new file mode 100644
index 00000000000..16751b47d03
--- /dev/null
+++ b/packages/styled-react/src/components/FeatureFlaggedTheming.tsx
@@ -0,0 +1,49 @@
+import {
+  ThemeProvider as PrimerReactThemeProvider,
+  type ThemeProviderProps,
+  BaseStyles as PrimerReactBaseStyles,
+  type BaseStylesProps,
+  useTheme as primerReactUseTheme,
+  useColorSchemeVar as primerReactUseColorSchemeVar,
+} from '@primer/react'
+import {
+  ThemeProvider as StyledReactThemeProvider,
+  useTheme as styledReactUseTheme,
+  useColorSchemeVar as styledReactUseColorSchemeVar,
+} from './ThemeProvider'
+import {BaseStyles as StyledReactBaseStyles} from './BaseStyles'
+import {useFeatureFlag} from '@primer/react/experimental'
+
+export const ThemeProvider: React.FC<React.PropsWithChildren<ThemeProviderProps>> = ({children, ...props}) => {
+  const enabled = useFeatureFlag('primer_react_use_styled_react_theming')
+  if (enabled) {
+    return <StyledReactThemeProvider {...props}>{children}</StyledReactThemeProvider>
+  } else {
+    return <PrimerReactThemeProvider {...props}>{children}</PrimerReactThemeProvider>
+  }
+}
+
+export const BaseStyles: React.FC<React.PropsWithChildren<BaseStylesProps>> = ({children, ...props}) => {
+  const enabled = useFeatureFlag('primer_react_use_styled_react_theming')
+  if (enabled) {
+    return <StyledReactBaseStyles {...props}>{children}</StyledReactBaseStyles>
+  } else {
+    return <PrimerReactBaseStyles {...props}>{children}</PrimerReactBaseStyles>
+  }
+}
+
+export const useTheme: typeof primerReactUseTheme = () => {
+  const enabled = useFeatureFlag('primer_react_use_styled_react_theming')
+  const styledReactResults = styledReactUseTheme()
+  const primerReactResults = primerReactUseTheme()
+
+  return enabled ? styledReactResults : primerReactResults
+}
+
+export const useColorSchemeVar: typeof primerReactUseColorSchemeVar = (values, fallback) => {
+  const enabled = useFeatureFlag('primer_react_use_styled_react_theming')
+  const styledReactResults = styledReactUseColorSchemeVar(values, fallback)
+  const primerReactResults = primerReactUseColorSchemeVar(values, fallback)
+
+  return enabled ? styledReactResults : primerReactResults
+}
diff --git a/packages/styled-react/src/index.tsx b/packages/styled-react/src/index.tsx
index 1f24c641214..14c29eb1ca9 100644
--- a/packages/styled-react/src/index.tsx
+++ b/packages/styled-react/src/index.tsx
@@ -12,8 +12,7 @@ export {TextInput} from '@primer/react'
 export {type TextInputProps} from '@primer/react'
 
 // theming depends on styled-components
-export {ThemeProvider, useTheme, useColorSchemeVar} from './components/ThemeProvider'
-export {BaseStyles} from './components/BaseStyles'
+export {ThemeProvider, useTheme, useColorSchemeVar, BaseStyles} from './components/FeatureFlaggedTheming'
 export {merge} from '@primer/react'
 export {theme} from '@primer/react'
 export {themeGet} from '@primer/react'

From 92f3196c2e52a4a680e747d2aed12895f956d251 Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Fri, 10 Oct 2025 12:55:00 +0200
Subject: [PATCH 15/16] add sad timeout

---
 e2e/components/IconButton.test.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/e2e/components/IconButton.test.ts b/e2e/components/IconButton.test.ts
index 99a4fde5546..3a77884c2f3 100644
--- a/e2e/components/IconButton.test.ts
+++ b/e2e/components/IconButton.test.ts
@@ -45,9 +45,9 @@ const stories = [
     disableAnimations: true,
     async setup(page: Page) {
       await page.keyboard.press('Tab') // focus on icon button
-      await page.getByText('Bold').waitFor({
-        state: 'visible',
-      })
+      await page.getByText('Bold').waitFor({state: 'visible'})
+      // eslint-disable-next-line playwright/no-wait-for-timeout
+      await page.waitForTimeout(100) // wait until after "tooltip delay" for a stable screenshot
     },
   },
   {

From 61165e5318601316b19d198ff53f5a383030409c Mon Sep 17 00:00:00 2001
From: Siddharth Kshetrapal <siddharthkp@github.com>
Date: Fri, 10 Oct 2025 13:10:40 +0200
Subject: [PATCH 16/16] wait longer

Increased wait time for tooltip delay to ensure stable screenshots.
---
 e2e/components/IconButton.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/e2e/components/IconButton.test.ts b/e2e/components/IconButton.test.ts
index 3a77884c2f3..955d22588f4 100644
--- a/e2e/components/IconButton.test.ts
+++ b/e2e/components/IconButton.test.ts
@@ -47,7 +47,7 @@ const stories = [
       await page.keyboard.press('Tab') // focus on icon button
       await page.getByText('Bold').waitFor({state: 'visible'})
       // eslint-disable-next-line playwright/no-wait-for-timeout
-      await page.waitForTimeout(100) // wait until after "tooltip delay" for a stable screenshot
+      await page.waitForTimeout(1000) // wait until after "tooltip delay" for a stable screenshot
     },
   },
   {