Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(theme): sync data-xds-theme to <html> for root provider; add LayerProvider to sandbox (#1587)

Cindy Zhang4c325c38b4b9
diff --git a/apps/sandbox/src/app/providers.tsx b/apps/sandbox/src/app/providers.tsx
index fb0b7d15e4..ab562b8080 100644
--- a/apps/sandbox/src/app/providers.tsx
+++ b/apps/sandbox/src/app/providers.tsx
@@ -2,6 +2,7 @@
import {useState, createContext, useContext, useEffect} from 'react';
import {XDSTheme} from '@xds/core/theme';
+import {XDSLayerProvider} from '@xds/core/Layer';
import {defaultTheme} from '@xds/theme-default/built';
import {neutralTheme} from '@xds/theme-neutral/built';
import {brutalistTheme} from '@xds/theme-brutalist/built';
@@ -47,7 +48,7 @@ export function Providers({children}: {children: React.ReactNode}) {
return (
<ThemeContext.Provider value={{themeName, setThemeName, mode, setMode}}>
<XDSTheme theme={theme} mode={mode}>
- {children}
+ <XDSLayerProvider>{children}</XDSLayerProvider>
</XDSTheme>
</ThemeContext.Provider>
);
diff --git a/packages/core/src/theme/XDSTheme.test.tsx b/packages/core/src/theme/XDSTheme.test.tsx
index 8402a7ec40..de18d8244c 100644
--- a/packages/core/src/theme/XDSTheme.test.tsx
+++ b/packages/core/src/theme/XDSTheme.test.tsx
@@ -22,11 +22,13 @@ describe('XDSTheme', () => {
beforeEach(() => {
// Clean up documentElement state before each test
document.documentElement.removeAttribute('data-theme');
+ document.documentElement.removeAttribute('data-xds-theme');
});
afterEach(() => {
cleanup();
document.documentElement.removeAttribute('data-theme');
+ document.documentElement.removeAttribute('data-xds-theme');
});
it('renders children', () => {
@@ -91,10 +93,52 @@ describe('XDSTheme', () => {
expect(document.documentElement.hasAttribute('data-theme')).toBe(false);
});
+ // =========================================================================
+ // Root detection — data-xds-theme on <html>
+ // =========================================================================
+
+ it('syncs data-xds-theme to <html> for root provider', () => {
+ render(
+ <XDSTheme theme={testTheme} mode="light">
+ <span>child</span>
+ </XDSTheme>,
+ );
+ expect(document.documentElement.getAttribute('data-xds-theme')).toBe(
+ 'test',
+ );
+ });
+
+ it('removes data-xds-theme from <html> when root provider unmounts', () => {
+ const {unmount} = render(
+ <XDSTheme theme={testTheme} mode="light">
+ <span>child</span>
+ </XDSTheme>,
+ );
+ expect(document.documentElement.getAttribute('data-xds-theme')).toBe(
+ 'test',
+ );
+ unmount();
+ expect(document.documentElement.hasAttribute('data-xds-theme')).toBe(false);
+ });
+
// =========================================================================
// Nested themes — should NOT sync to <html>
// =========================================================================
+ it('does not let nested XDSTheme override <html> data-xds-theme', () => {
+ render(
+ <XDSTheme theme={testTheme} mode="dark">
+ <XDSTheme theme={altTheme} mode="light">
+ <span>nested</span>
+ </XDSTheme>
+ </XDSTheme>,
+ );
+ // Root is "test" — nested "alt" should NOT override
+ expect(document.documentElement.getAttribute('data-xds-theme')).toBe(
+ 'test',
+ );
+ });
+
it('does not let nested XDSTheme override <html> data-theme', () => {
render(
<XDSTheme theme={testTheme} mode="dark">
diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsx
index dfa25d46d3..4b90a069fe 100644
--- a/packages/core/src/theme/XDSTheme.tsx
+++ b/packages/core/src/theme/XDSTheme.tsx
@@ -9,9 +9,11 @@
* - Component overrides scoped via @scope'd CSS selectors on .xds-* classes
*
* Root detection: The first XDSTheme in the tree (no parent XDSTheme)
- * automatically syncs `data-theme` to `document.documentElement`, which
- * drives `color-scheme` via reset.css rules. This ensures browser chrome
- * (scrollbars, native form controls, date pickers) reflects the active mode.
+ * automatically syncs attributes to `document.documentElement`:
+ * - `data-theme` — drives `color-scheme` via reset.css rules, ensuring browser
+ * chrome (scrollbars, native form controls, date pickers) reflects the mode.
+ * - `data-xds-theme` — enables @scope'd theme CSS to reach elements rendered
+ * outside the XDSTheme wrapper (portals, toast fallback viewports).
*
* For RSC / SSR, set `data-theme` on `<html>` in your root server layout
* to avoid a flash of wrong theme before hydration:
@@ -244,16 +246,23 @@ function useThemeFontLoading(theme: XDSDefinedTheme): void {
// =============================================================================
/**
- * Hook to sync data-theme to document.documentElement for the root provider.
+ * Hook to sync theme attributes to document.documentElement for the root provider.
* Skipped for nested XDSTheme instances.
*
- * reset.css maps [data-theme] to color-scheme, which controls browser chrome
- * (scrollbars, native form controls, date pickers).
+ * Syncs two attributes:
+ * - `data-theme` (light/dark) — reset.css maps this to color-scheme, controlling
+ * browser chrome (scrollbars, native form controls, date pickers).
+ * - `data-xds-theme` (theme name) — enables @scope'd theme CSS to reach elements
+ * outside the XDSTheme wrapper (e.g. toast fallback viewports, portals).
*
* - 'light' | 'dark' → sets data-theme="light" | "dark"
* - 'system' → removes data-theme (reset.css defaults to color-scheme: light dark)
*/
-function useRootColorSchemeSync(isNested: boolean, mode: ThemeMode): void {
+function useRootThemeSync(
+ isNested: boolean,
+ mode: ThemeMode,
+ themeName: string,
+): void {
useLayoutEffect(() => {
if (isNested) return;
if (typeof document === 'undefined') return;
@@ -265,10 +274,14 @@ function useRootColorSchemeSync(isNested: boolean, mode: ThemeMode): void {
document.documentElement.removeAttribute('data-theme');
}
+ // Sync theme name so @scope rules reach portals/fallback viewports
+ document.documentElement.setAttribute('data-xds-theme', themeName);
+
return () => {
document.documentElement.removeAttribute('data-theme');
+ document.documentElement.removeAttribute('data-xds-theme');
};
- }, [isNested, mode]);
+ }, [isNested, mode, themeName]);
}
// =============================================================================
@@ -283,8 +296,8 @@ function useRootColorSchemeSync(isNested: boolean, mode: ThemeMode): void {
* components render with their .xds-* class and don't need context.
*
* When this is the root XDSTheme (no parent XDSTheme in the tree),
- * it syncs `data-theme` to `<html>` so browser chrome elements
- * (scrollbars, form controls, date pickers) reflect the active mode.
+ * it syncs `data-theme` and `data-xds-theme` to `<html>` so browser
+ * chrome reflects the active mode and @scope'd CSS reaches portals.
* Nested XDSTheme instances skip the sync.
*/
export function XDSTheme({
@@ -296,7 +309,7 @@ export function XDSTheme({
useThemeStyleInjection(theme);
useThemeFontLoading(theme);
- useRootColorSchemeSync(isNested, mode);
+ useRootThemeSync(isNested, mode, theme.name);
// Get color-scheme style
const colorSchemeStyle =