Theme: phrase the optimization in mechanism-neutral terms

In anticipation of #78678, which replaces ThemeProvider's per-instance
`<style>` element with inline custom properties on the wrapper, reword
the comments / CHANGELOG / README / PR description to describe the
optimization as "skip applying per-instance overrides" rather than
"skip emitting the `<style>` element". The savings are real in either
mechanism (no CSS string assembly + no DOM write).

Also simplify the `AcrossIframes` story:
- The previous filter cloned `<style data-wpds-theme-provider-id>`
  elements from `document.head`, which is dead code (React-rendered
  `<style>` is not in head) and would be doubly dead post-#78678
  (the attribute is removed entirely). Drop it.
- Per-instance overrides ride into the iframe with the portalled
  `<ThemeProvider>` itself (whether the mechanism is a `<style>`
  child or an inline `style` prop on the wrapper). The story only
  needs to clone the prebuilt token stylesheet `<link>`.

Author: ciampo

packages/theme/CHANGELOG.md

@@ -15,7 +15,7 @@
 ### Internal
 
 -   Refactor color space registration to avoid module-level side effects ([#77653](https://github.com/WordPress/gutenberg/pull/77653)).
--   `ThemeProvider`: skip emitting the per-instance `<style>` element entirely when the resolved settings match the prebuilt defaults. `--wp-admin-theme-color*` overrides are now emitted only when the resolved `color.primary` differs from the prebuilt default, letting WP Core's admin color scheme show through otherwise ([#78664](https://github.com/WordPress/gutenberg/pull/78664)).
+-   `ThemeProvider`: skip applying per-instance overrides entirely when the resolved settings match the prebuilt defaults. `--wp-admin-theme-color*` overrides are now applied only when the resolved `color.primary` differs from the prebuilt default, letting WP Core's admin color scheme show through otherwise ([#78664](https://github.com/WordPress/gutenberg/pull/78664)).
 -   Within the block editor iframe, default WPDS tokens (`--wpds-*`) are now available at `:root` even without a `<ThemeProvider>` instance, matching the main admin document ([#78664](https://github.com/WordPress/gutenberg/pull/78664)).
 
 ## 0.13.0 (2026-05-14)

packages/theme/README.md

@@ -24,9 +24,9 @@ The [`ThemeProvider`](#theme-provider) component can be used to customize token
 The design system splits token delivery into two complementary layers:
 
 -   **Static stylesheet (`design-tokens.css`)** — defines the default values for every `--wpds-*` and `--wp-components-*` custom property at the document `:root`. Loaded once per document (the main page, _and_ each iframe you render React into). Provides a working baseline even before any JavaScript runs.
--   **Runtime `<ThemeProvider>`** — emits a per-instance `<style>` element only when the resolved settings differ from the static defaults. Use it to override individual settings (e.g. `color.primary`, `cursor.control`, `density`) for a subtree.
+-   **Runtime `<ThemeProvider>`** — applies per-instance overrides only when the resolved settings differ from the static defaults. Use it to override individual settings (e.g. `color.primary`, `cursor.control`, `density`) for a subtree.
 
-A `<ThemeProvider>` whose resolved settings match the defaults is intentionally a no-op for CSS emission — the static stylesheet already supplies every variable.
+A `<ThemeProvider>` whose resolved settings match the defaults is intentionally a no-op — the static stylesheet already supplies every variable.
 
 #### Within WordPress
 

packages/theme/src/stories/index.story.tsx

@@ -303,39 +303,24 @@ function IframeWithClonedTokenStyles( {
 	const [ iframeLoaded, setIframeLoaded ] = useState( false );
 
 	// Make DS tokens available inside the iframe. In real WordPress this is
-	// handled by enqueuing the prebuilt token stylesheet and routing per-
-	// instance overrides through `StyleProvider`; Storybook has no enqueue
-	// layer, so we replicate it by cloning the prebuilt token stylesheet
-	// plus any `<style>` emitted by a nested `<ThemeProvider>`.
+	// handled by enqueuing the prebuilt token stylesheet; Storybook has no
+	// enqueue layer, so we clone its `<link>` into the iframe here. Any
+	// per-instance overrides travel into the iframe with the portalled
+	// `<ThemeProvider>` itself.
 	useEffect( () => {
 		const iframe = iframeRef.current;
 		if ( ! iframe || ! iframe.contentDocument ) {
 			return;
 		}
 
-		const head = iframe.contentDocument.head;
-
-		const allNodes = Array.from(
-			document.head.querySelectorAll( 'style, link[rel="stylesheet"]' )
+		const tokensLink = document.head.querySelector(
+			'link[rel="stylesheet"][href*="design-tokens"]'
 		);
-
-		allNodes.forEach( ( node ) => {
-			if ( node.tagName === 'STYLE' ) {
-				// Per-instance overrides carry this data attribute.
-				if (
-					( node as HTMLStyleElement ).dataset.wpdsThemeProviderId !==
-					undefined
-				) {
-					head.appendChild( node.cloneNode( true ) );
-				}
-			} else if (
-				node.tagName === 'LINK' &&
-				( node as HTMLLinkElement ).href.includes( 'design-tokens' )
-			) {
-				// Prebuilt token stylesheet.
-				head.appendChild( node.cloneNode( true ) );
-			}
-		} );
+		if ( tokensLink ) {
+			iframe.contentDocument.head.appendChild(
+				tokensLink.cloneNode( true )
+			);
+		}
 
 		setIframeLoaded( true );
 	}, [] );

packages/theme/src/use-theme-provider-styles.ts

@@ -140,9 +140,10 @@ export function useThemeProviderStyles( {
 	);
 
 	// When everything resolves to the WPDS defaults, the prebuilt `:root` CSS
-	// already provides every variable, so skip the per-instance `<style>`.
-	// `colorjs.io`'s `equals` treats any parseable representation of the
-	// same color as default (e.g. `#3858E9` ≡ `#3858e9` ≡ `rgb(56 88 233)`).
+	// already provides every variable; return `undefined` so the provider
+	// applies no per-instance overrides. `colorjs.io`'s `equals` treats any
+	// parseable representation of the same color as default (e.g. `#3858E9`
+	// ≡ `#3858e9` ≡ `rgb(56 88 233)`).
 	let primaryIsDefault = false;
 	let bgIsDefault = false;
 	try {