From 8e680fb2e23b1db66e520e8f240b337cdea36a8a Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Thu, 11 Jun 2026 19:16:43 +0200
Subject: [PATCH 01/12] Theme: Add tests for ThemeProvider and
 useThemeProviderStyles

Covers defaults, explicit color/cursor settings, inheritance and overrides
from a parent provider, nested providers, and the `isRoot` selector
behavior. Addresses point T1 of #77462.
---
 package-lock.json                             |   2 +
 packages/theme/package.json                   |   2 +
 .../theme/src/test/theme-provider.test.tsx    | 137 ++++++++++++++++++
 .../test/use-theme-provider-styles.test.tsx   | 123 ++++++++++++++++
 4 files changed, 264 insertions(+)
 create mode 100644 packages/theme/src/test/theme-provider.test.tsx
 create mode 100644 packages/theme/src/test/use-theme-provider-styles.test.tsx

diff --git a/package-lock.json b/package-lock.json
index 864a91e3cf051f..c38c9a38c2856c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -53021,7 +53021,9 @@
 				"@terrazzo/parser": "^2.0.3",
 				"@terrazzo/plugin-css": "^2.0.3",
 				"@terrazzo/token-tools": "^2.0.3",
+				"@testing-library/dom": "^10.4.1",
 				"@testing-library/jest-dom": "^6.9.1",
+				"@testing-library/react": "^16.3.2",
 				"@types/jest": "^29.5.14",
 				"@types/node": "^20.19.39",
 				"esbuild": "^0.27.2",
diff --git a/packages/theme/package.json b/packages/theme/package.json
index 85a57d825e7090..05119f08fcbad0 100644
--- a/packages/theme/package.json
+++ b/packages/theme/package.json
@@ -91,7 +91,9 @@
 		"@terrazzo/parser": "^2.0.3",
 		"@terrazzo/plugin-css": "^2.0.3",
 		"@terrazzo/token-tools": "^2.0.3",
+		"@testing-library/dom": "^10.4.1",
 		"@testing-library/jest-dom": "^6.9.1",
+		"@testing-library/react": "^16.3.2",
 		"@types/jest": "^29.5.14",
 		"@types/node": "^20.19.39",
 		"esbuild": "^0.27.2",
diff --git a/packages/theme/src/test/theme-provider.test.tsx b/packages/theme/src/test/theme-provider.test.tsx
new file mode 100644
index 00000000000000..66b35fb268e70e
--- /dev/null
+++ b/packages/theme/src/test/theme-provider.test.tsx
@@ -0,0 +1,137 @@
+// These tests intentionally assert on the non-semantic DOM that the provider
+// produces — the injected `<style>` element and the `data-*` scoping attributes
+// — which have no accessible role to query through Testing Library.
+/* eslint-disable testing-library/no-container, testing-library/no-node-access */
+
+import { render, screen } from '@testing-library/react';
+import { ThemeProvider } from '../theme-provider';
+
+function getProvider( container: HTMLElement ) {
+	return container.querySelector< HTMLElement >(
+		'[data-wpds-theme-provider-id]'
+	);
+}
+
+function getStyleText( container: HTMLElement ) {
+	return container.querySelector( 'style' )?.textContent ?? '';
+}
+
+describe( 'ThemeProvider', () => {
+	it( 'renders its children', () => {
+		render( <ThemeProvider>content</ThemeProvider> );
+
+		expect( screen.getByText( 'content' ) ).toBeInTheDocument();
+	} );
+
+	it( 'renders a wrapper element with the provider metadata attributes', () => {
+		const { container } = render( <ThemeProvider>x</ThemeProvider> );
+		const provider = getProvider( container );
+
+		expect( provider ).toHaveAttribute( 'data-wpds-theme-provider-id' );
+		expect( provider ).toHaveAttribute(
+			'data-wpds-root-provider',
+			'false'
+		);
+	} );
+
+	it( 'generates a unique instance id for each provider', () => {
+		const { container } = render(
+			<>
+				<ThemeProvider>a</ThemeProvider>
+				<ThemeProvider>b</ThemeProvider>
+			</>
+		);
+
+		const ids = Array.from(
+			container.querySelectorAll( '[data-wpds-theme-provider-id]' )
+		).map( ( el ) => el.getAttribute( 'data-wpds-theme-provider-id' ) );
+
+		expect( ids ).toHaveLength( 2 );
+		expect( ids[ 0 ] ).toBeTruthy();
+		expect( ids[ 0 ] ).not.toBe( ids[ 1 ] );
+	} );
+
+	describe( 'style element', () => {
+		it( 'scopes the custom properties to the provider instance id', () => {
+			const { container } = render(
+				<ThemeProvider color={ { primary: '#ff0000' } }>
+					x
+				</ThemeProvider>
+			);
+			const instanceId = getProvider( container )?.getAttribute(
+				'data-wpds-theme-provider-id'
+			);
+			const styleText = getStyleText( container );
+
+			expect( styleText ).toContain(
+				`[data-wpds-theme-provider-id="${ instanceId }"]`
+			);
+			// The generated declarations include the color tokens.
+			expect( styleText ).toContain( '--wp-admin-theme-color' );
+		} );
+
+		it( 'sets the cursor control custom property when requested', () => {
+			const { container } = render(
+				<ThemeProvider cursor={ { control: 'pointer' } }>
+					x
+				</ThemeProvider>
+			);
+
+			expect( getStyleText( container ) ).toContain(
+				'--wpds-cursor-control: pointer'
+			);
+		} );
+	} );
+
+	describe( 'isRoot selector', () => {
+		it( 'does not target the document root by default', () => {
+			const { container } = render(
+				<ThemeProvider color={ { primary: '#ff0000' } }>
+					x
+				</ThemeProvider>
+			);
+
+			expect( getProvider( container ) ).toHaveAttribute(
+				'data-wpds-root-provider',
+				'false'
+			);
+			expect( getStyleText( container ) ).not.toContain( ':root:has(' );
+		} );
+
+		it( 'targets the document root when isRoot is set', () => {
+			const { container } = render(
+				<ThemeProvider isRoot color={ { primary: '#ff0000' } }>
+					x
+				</ThemeProvider>
+			);
+
+			expect( getProvider( container ) ).toHaveAttribute(
+				'data-wpds-root-provider',
+				'true'
+			);
+			const styleText = getStyleText( container );
+			expect( styleText ).toContain( ':root:has(' );
+			expect( styleText ).toContain( '[data-wpds-root-provider="true"]' );
+		} );
+	} );
+
+	describe( 'nested providers', () => {
+		it( 'renders a distinct scope and style for each provider', () => {
+			const { container } = render(
+				<ThemeProvider color={ { primary: '#ff0000' } }>
+					<ThemeProvider color={ { primary: '#00ff00' } }>
+						nested
+					</ThemeProvider>
+				</ThemeProvider>
+			);
+
+			expect(
+				container.querySelectorAll( '[data-wpds-theme-provider-id]' )
+			).toHaveLength( 2 );
+			expect( container.querySelectorAll( 'style' ) ).toHaveLength( 2 );
+			expect( screen.getByText( 'nested' ) ).toBeInTheDocument();
+		} );
+	} );
+} );
+
+/* eslint-enable testing-library/no-container, testing-library/no-node-access */
diff --git a/packages/theme/src/test/use-theme-provider-styles.test.tsx b/packages/theme/src/test/use-theme-provider-styles.test.tsx
new file mode 100644
index 00000000000000..567128e641ec75
--- /dev/null
+++ b/packages/theme/src/test/use-theme-provider-styles.test.tsx
@@ -0,0 +1,123 @@
+import { renderHook } from '@testing-library/react';
+import { type ReactNode } from 'react';
+import { ThemeProvider } from '../theme-provider';
+import { useThemeProviderStyles } from '../use-theme-provider-styles';
+import { DEFAULT_SEED_COLORS } from '../color-ramps';
+
+type Styles = Record< string, string >;
+
+describe( 'useThemeProviderStyles', () => {
+	describe( 'defaults', () => {
+		it( 'resolves to the default seed colors when no settings are provided', () => {
+			const { result } = renderHook( () => useThemeProviderStyles() );
+
+			expect( result.current.resolvedSettings.color ).toEqual( {
+				primary: DEFAULT_SEED_COLORS.primary,
+				background: DEFAULT_SEED_COLORS.background,
+			} );
+			expect( result.current.resolvedSettings.cursor ).toBeUndefined();
+		} );
+
+		it( 'returns custom properties for the semantic and legacy tokens', () => {
+			const { result } = renderHook( () => useThemeProviderStyles() );
+			const styles = result.current.themeProviderStyles;
+
+			// Semantic design-system tokens.
+			expect( Object.keys( styles ) ).toEqual(
+				expect.arrayContaining( [
+					expect.stringMatching( /^--wpds-color-/ ),
+				] )
+			);
+			// Legacy `wp-admin` / `wp-components` overrides.
+			expect( styles ).toHaveProperty( '--wp-admin-theme-color' );
+			expect( styles ).toHaveProperty( '--wp-components-color-accent' );
+		} );
+
+		it( 'does not set the cursor custom property', () => {
+			const { result } = renderHook( () => useThemeProviderStyles() );
+
+			expect( result.current.themeProviderStyles ).not.toHaveProperty(
+				'--wpds-cursor-control'
+			);
+		} );
+	} );
+
+	describe( 'explicit settings', () => {
+		it( 'uses the provided primary color', () => {
+			const { result } = renderHook( () =>
+				useThemeProviderStyles( { color: { primary: '#ff0000' } } )
+			);
+
+			expect( result.current.resolvedSettings.color?.primary ).toBe(
+				'#ff0000'
+			);
+			// The background falls back to the default seed.
+			expect( result.current.resolvedSettings.color?.background ).toBe(
+				DEFAULT_SEED_COLORS.background
+			);
+		} );
+
+		it( 'sets the cursor control custom property', () => {
+			const { result } = renderHook( () =>
+				useThemeProviderStyles( { cursor: { control: 'pointer' } } )
+			);
+
+			expect( result.current.resolvedSettings.cursor ).toEqual( {
+				control: 'pointer',
+			} );
+			expect(
+				( result.current.themeProviderStyles as Styles )[
+					'--wpds-cursor-control'
+				]
+			).toBe( 'pointer' );
+		} );
+	} );
+
+	describe( 'inheritance from a parent provider', () => {
+		const wrapper = ( { children }: { children: ReactNode } ) => (
+			<ThemeProvider
+				color={ { primary: '#abcdef', background: '#222222' } }
+				cursor={ { control: 'pointer' } }
+			>
+				{ children }
+			</ThemeProvider>
+		);
+
+		it( 'inherits color and cursor settings when none are provided locally', () => {
+			const { result } = renderHook( () => useThemeProviderStyles(), {
+				wrapper,
+			} );
+
+			expect( result.current.resolvedSettings.color ).toEqual( {
+				primary: '#abcdef',
+				background: '#222222',
+			} );
+			expect( result.current.resolvedSettings.cursor ).toEqual( {
+				control: 'pointer',
+			} );
+		} );
+
+		it( 'lets local settings override the inherited ones', () => {
+			const { result } = renderHook(
+				() =>
+					useThemeProviderStyles( {
+						color: { primary: '#00ff00' },
+						cursor: { control: 'default' },
+					} ),
+				{ wrapper }
+			);
+
+			// Locally provided values win.
+			expect( result.current.resolvedSettings.color?.primary ).toBe(
+				'#00ff00'
+			);
+			expect( result.current.resolvedSettings.cursor ).toEqual( {
+				control: 'default',
+			} );
+			// Values not provided locally keep inheriting from the parent.
+			expect( result.current.resolvedSettings.color?.background ).toBe(
+				'#222222'
+			);
+		} );
+	} );
+} );

From 845cdc18790f3f34f57fc990a2e3a183c16bb234 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Fri, 12 Jun 2026 09:17:16 +0200
Subject: [PATCH 02/12] Theme: Strengthen ThemeProvider scoping assertions in
 tests

Mock the CSS module with a real class name so the generated scoping
selectors (class + instance id, and the `:root:has()` selector for
`isRoot`) and the wrapper's class are actually validated, instead of
passing against an `undefined` class from the global CSS mock.
---
 .../theme/src/test/theme-provider.test.tsx    | 23 +++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/packages/theme/src/test/theme-provider.test.tsx b/packages/theme/src/test/theme-provider.test.tsx
index 66b35fb268e70e..12d2e2ad7f91bf 100644
--- a/packages/theme/src/test/theme-provider.test.tsx
+++ b/packages/theme/src/test/theme-provider.test.tsx
@@ -6,6 +6,13 @@
 import { render, screen } from '@testing-library/react';
 import { ThemeProvider } from '../theme-provider';
 
+// The global Jest setup maps CSS modules to an empty object, which would leave
+// the provider's scoping class `undefined`. Provide a real class name so the
+// generated selectors and the wrapper's class can be asserted meaningfully.
+jest.mock( '../style.module.css', () => ( {
+	root: 'theme-provider-root',
+} ) );
+
 function getProvider( container: HTMLElement ) {
 	return container.querySelector< HTMLElement >(
 		'[data-wpds-theme-provider-id]'
@@ -27,6 +34,7 @@ describe( 'ThemeProvider', () => {
 		const { container } = render( <ThemeProvider>x</ThemeProvider> );
 		const provider = getProvider( container );
 
+		expect( provider ).toHaveClass( 'theme-provider-root' );
 		expect( provider ).toHaveAttribute( 'data-wpds-theme-provider-id' );
 		expect( provider ).toHaveAttribute(
 			'data-wpds-root-provider',
@@ -63,8 +71,10 @@ describe( 'ThemeProvider', () => {
 			);
 			const styleText = getStyleText( container );
 
+			// The instance selector scopes to both the provider's class (with
+			// the intentional doubled specificity) and its unique instance id.
 			expect( styleText ).toContain(
-				`[data-wpds-theme-provider-id="${ instanceId }"]`
+				`.theme-provider-root.theme-provider-root[data-wpds-theme-provider-id="${ instanceId }"]`
 			);
 			// The generated declarations include the color tokens.
 			expect( styleText ).toContain( '--wp-admin-theme-color' );
@@ -109,9 +119,14 @@ describe( 'ThemeProvider', () => {
 				'data-wpds-root-provider',
 				'true'
 			);
-			const styleText = getStyleText( container );
-			expect( styleText ).toContain( ':root:has(' );
-			expect( styleText ).toContain( '[data-wpds-root-provider="true"]' );
+			const instanceId = getProvider( container )?.getAttribute(
+				'data-wpds-theme-provider-id'
+			);
+			// The document root is targeted via `:has()`, matching the
+			// provider's class, the root flag, and its unique instance id.
+			expect( getStyleText( container ) ).toContain(
+				`:root:has(.theme-provider-root[data-wpds-root-provider="true"][data-wpds-theme-provider-id="${ instanceId }"])`
+			);
 		} );
 	} );
 

From 41baa72e20add2cceb5a25b3be4be208447e5ae6 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Fri, 12 Jun 2026 09:26:59 +0200
Subject: [PATCH 03/12] Theme: Fix package-lock.json sync for new test
 devDependencies

Regenerate the lockfile entries for `@testing-library/react` /
`@testing-library/dom` with the repo's pinned npm (Node 20) so that
`npm ci` is satisfied in CI.
---
 package-lock.json | 65 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/package-lock.json b/package-lock.json
index c38c9a38c2856c..50489b62a1d90a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -53083,6 +53083,49 @@
 				"wildcard-match": "^5.1.4"
 			}
 		},
+		"packages/theme/node_modules/@testing-library/dom": {
+			"version": "10.4.1",
+			"resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",
+			"integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/code-frame": "^7.10.4",
+				"@babel/runtime": "^7.12.5",
+				"@types/aria-query": "^5.0.1",
+				"aria-query": "5.3.0",
+				"dom-accessibility-api": "^0.5.9",
+				"lz-string": "^1.5.0",
+				"picocolors": "1.1.1",
+				"pretty-format": "^27.0.2"
+			},
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"packages/theme/node_modules/ansi-styles": {
+			"version": "5.2.0",
+			"resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
+			"integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=10"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/ansi-styles?sponsor=1"
+			}
+		},
+		"packages/theme/node_modules/aria-query": {
+			"version": "5.3.0",
+			"resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.0.tgz",
+			"integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==",
+			"dev": true,
+			"license": "Apache-2.0",
+			"dependencies": {
+				"dequal": "^2.0.3"
+			}
+		},
 		"packages/theme/node_modules/colorjs.io": {
 			"version": "0.6.1",
 			"resolved": "https://registry.npmjs.org/colorjs.io/-/colorjs.io-0.6.1.tgz",
@@ -53093,6 +53136,28 @@
 				"url": "https://opencollective.com/color"
 			}
 		},
+		"packages/theme/node_modules/pretty-format": {
+			"version": "27.5.1",
+			"resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz",
+			"integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"ansi-regex": "^5.0.1",
+				"ansi-styles": "^5.0.0",
+				"react-is": "^17.0.1"
+			},
+			"engines": {
+				"node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0"
+			}
+		},
+		"packages/theme/node_modules/react-is": {
+			"version": "17.0.2",
+			"resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz",
+			"integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
+			"dev": true,
+			"license": "MIT"
+		},
 		"packages/token-list": {
 			"name": "@wordpress/token-list",
 			"version": "3.48.0",

From a8bcb48f3567996f573855ffb63a34ed3df9eee4 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Fri, 12 Jun 2026 09:28:18 +0200
Subject: [PATCH 04/12] Theme: Add CHANGELOG entry for ThemeProvider tests

---
 packages/theme/CHANGELOG.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/theme/CHANGELOG.md b/packages/theme/CHANGELOG.md
index 29ca8fb5d54e05..4643eec483b055 100644
--- a/packages/theme/CHANGELOG.md
+++ b/packages/theme/CHANGELOG.md
@@ -16,6 +16,10 @@
 
 -   `ThemeProvider`: Strictly enforce the documented seed-color input contract for `color.primary` / `color.background`. Inputs outside sRGB (e.g. `oklch()`), previously accepted incidentally, now throw a clear error ([#79148](https://github.com/WordPress/gutenberg/pull/79148)).
 
+### Internal
+
+-   Add unit tests for `ThemeProvider` and `useThemeProviderStyles` ([#79126](https://github.com/WordPress/gutenberg/pull/79126)).
+
 ## 0.15.0 (2026-06-10)
 
 ### New Features

From 4a38b6c8e4c4aab0217da53aace80154f279f99f Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Fri, 12 Jun 2026 10:15:49 +0200
Subject: [PATCH 05/12] Theme: Assert computed custom properties in
 ThemeProvider tests

Replace the brittle selector-string assertions with behavior-focused
checks that read the resolved CSS custom properties via
`getComputedStyle`: defined within the provider's subtree, absent
outside it, applied to the document root for `isRoot`, and correctly
inherited/overridden across nested providers.
---
 .../theme/src/test/theme-provider.test.tsx    | 171 ++++++++----------
 1 file changed, 72 insertions(+), 99 deletions(-)

diff --git a/packages/theme/src/test/theme-provider.test.tsx b/packages/theme/src/test/theme-provider.test.tsx
index 12d2e2ad7f91bf..c6e9be48dc54d0 100644
--- a/packages/theme/src/test/theme-provider.test.tsx
+++ b/packages/theme/src/test/theme-provider.test.tsx
@@ -1,26 +1,29 @@
-// These tests intentionally assert on the non-semantic DOM that the provider
-// produces — the injected `<style>` element and the `data-*` scoping attributes
-// — which have no accessible role to query through Testing Library.
-/* eslint-disable testing-library/no-container, testing-library/no-node-access */
+// These tests read the resolved CSS custom properties produced by the provider.
+// jsdom does not cascade custom properties to descendant elements, so the value
+// is asserted on the provider's own scoping element (where the property is
+// defined and from which real children would inherit) and on the document root.
 
 import { render, screen } from '@testing-library/react';
 import { ThemeProvider } from '../theme-provider';
 
-// The global Jest setup maps CSS modules to an empty object, which would leave
-// the provider's scoping class `undefined`. Provide a real class name so the
-// generated selectors and the wrapper's class can be asserted meaningfully.
+// Mock the CSS module so the provider's scoping class is a real, stable class
+// name. Without this the global Jest CSS mock leaves the class `undefined`, and
+// jsdom cannot match the generated rules to compute the custom properties.
 jest.mock( '../style.module.css', () => ( {
 	root: 'theme-provider-root',
 } ) );
 
-function getProvider( container: HTMLElement ) {
-	return container.querySelector< HTMLElement >(
-		'[data-wpds-theme-provider-id]'
-	);
+// The legacy accent property is set to the seed color's sRGB channels, which
+// makes the expected value predictable regardless of color serialization.
+const ACCENT_RGB = '--wp-admin-theme-color--rgb';
+
+function readProp( element: Element, property: string ) {
+	return getComputedStyle( element ).getPropertyValue( property ).trim();
 }
 
-function getStyleText( container: HTMLElement ) {
-	return container.querySelector( 'style' )?.textContent ?? '';
+// The `ThemeProvider` wrapper element that scopes the given descendant.
+function getScopingProvider( element: Element ) {
+	return element.closest< HTMLElement >( '[data-wpds-theme-provider-id]' )!;
 }
 
 describe( 'ThemeProvider', () => {
@@ -30,123 +33,93 @@ describe( 'ThemeProvider', () => {
 		expect( screen.getByText( 'content' ) ).toBeInTheDocument();
 	} );
 
-	it( 'renders a wrapper element with the provider metadata attributes', () => {
-		const { container } = render( <ThemeProvider>x</ThemeProvider> );
-		const provider = getProvider( container );
-
-		expect( provider ).toHaveClass( 'theme-provider-root' );
-		expect( provider ).toHaveAttribute( 'data-wpds-theme-provider-id' );
-		expect( provider ).toHaveAttribute(
-			'data-wpds-root-provider',
-			'false'
+	it( 'defines the themed custom property within its subtree', () => {
+		render(
+			<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
+				<div data-testid="child">x</div>
+			</ThemeProvider>
 		);
+
+		const provider = getScopingProvider( screen.getByTestId( 'child' ) );
+		expect( readProp( provider, ACCENT_RGB ) ).toBe( '255, 0, 0' );
 	} );
 
-	it( 'generates a unique instance id for each provider', () => {
-		const { container } = render(
-			<>
-				<ThemeProvider>a</ThemeProvider>
-				<ThemeProvider>b</ThemeProvider>
-			</>
+	it( 'does not define the custom property outside of the provider', () => {
+		render(
+			<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
+				x
+			</ThemeProvider>
 		);
 
-		const ids = Array.from(
-			container.querySelectorAll( '[data-wpds-theme-provider-id]' )
-		).map( ( el ) => el.getAttribute( 'data-wpds-theme-provider-id' ) );
+		const outside = document.createElement( 'div' );
+		document.body.appendChild( outside );
 
-		expect( ids ).toHaveLength( 2 );
-		expect( ids[ 0 ] ).toBeTruthy();
-		expect( ids[ 0 ] ).not.toBe( ids[ 1 ] );
+		expect( readProp( outside, ACCENT_RGB ) ).toBe( '' );
 	} );
 
-	describe( 'style element', () => {
-		it( 'scopes the custom properties to the provider instance id', () => {
-			const { container } = render(
-				<ThemeProvider color={ { primary: '#ff0000' } }>
-					x
-				</ThemeProvider>
-			);
-			const instanceId = getProvider( container )?.getAttribute(
-				'data-wpds-theme-provider-id'
-			);
-			const styleText = getStyleText( container );
-
-			// The instance selector scopes to both the provider's class (with
-			// the intentional doubled specificity) and its unique instance id.
-			expect( styleText ).toContain(
-				`.theme-provider-root.theme-provider-root[data-wpds-theme-provider-id="${ instanceId }"]`
-			);
-			// The generated declarations include the color tokens.
-			expect( styleText ).toContain( '--wp-admin-theme-color' );
-		} );
-
-		it( 'sets the cursor control custom property when requested', () => {
-			const { container } = render(
-				<ThemeProvider cursor={ { control: 'pointer' } }>
-					x
-				</ThemeProvider>
-			);
+	it( 'applies the cursor custom property when set', () => {
+		render(
+			<ThemeProvider cursor={ { control: 'pointer' } }>
+				<div data-testid="child">x</div>
+			</ThemeProvider>
+		);
 
-			expect( getStyleText( container ) ).toContain(
-				'--wpds-cursor-control: pointer'
-			);
-		} );
+		const provider = getScopingProvider( screen.getByTestId( 'child' ) );
+		expect( readProp( provider, '--wpds-cursor-control' ) ).toBe(
+			'pointer'
+		);
 	} );
 
-	describe( 'isRoot selector', () => {
-		it( 'does not target the document root by default', () => {
-			const { container } = render(
-				<ThemeProvider color={ { primary: '#ff0000' } }>
+	describe( 'isRoot', () => {
+		it( 'defines the custom property on the document root', () => {
+			render(
+				<ThemeProvider isRoot color={ { primary: 'rgb(255, 0, 0)' } }>
 					x
 				</ThemeProvider>
 			);
 
-			expect( getProvider( container ) ).toHaveAttribute(
-				'data-wpds-root-provider',
-				'false'
+			expect( readProp( document.documentElement, ACCENT_RGB ) ).toBe(
+				'255, 0, 0'
 			);
-			expect( getStyleText( container ) ).not.toContain( ':root:has(' );
 		} );
 
-		it( 'targets the document root when isRoot is set', () => {
-			const { container } = render(
-				<ThemeProvider isRoot color={ { primary: '#ff0000' } }>
+		it( 'does not affect the document root by default', () => {
+			render(
+				<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
 					x
 				</ThemeProvider>
 			);
 
-			expect( getProvider( container ) ).toHaveAttribute(
-				'data-wpds-root-provider',
-				'true'
-			);
-			const instanceId = getProvider( container )?.getAttribute(
-				'data-wpds-theme-provider-id'
-			);
-			// The document root is targeted via `:has()`, matching the
-			// provider's class, the root flag, and its unique instance id.
-			expect( getStyleText( container ) ).toContain(
-				`:root:has(.theme-provider-root[data-wpds-root-provider="true"][data-wpds-theme-provider-id="${ instanceId }"])`
+			expect( readProp( document.documentElement, ACCENT_RGB ) ).toBe(
+				''
 			);
 		} );
 	} );
 
 	describe( 'nested providers', () => {
-		it( 'renders a distinct scope and style for each provider', () => {
-			const { container } = render(
-				<ThemeProvider color={ { primary: '#ff0000' } }>
-					<ThemeProvider color={ { primary: '#00ff00' } }>
-						nested
+		it( 'inherits the parent value, and a nested provider can override it', () => {
+			render(
+				<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
+					<ThemeProvider>
+						<div data-testid="inheriting">a</div>
+					</ThemeProvider>
+					<ThemeProvider color={ { primary: 'rgb(0, 255, 0)' } }>
+						<div data-testid="overriding">b</div>
 					</ThemeProvider>
 				</ThemeProvider>
 			);
 
-			expect(
-				container.querySelectorAll( '[data-wpds-theme-provider-id]' )
-			).toHaveLength( 2 );
-			expect( container.querySelectorAll( 'style' ) ).toHaveLength( 2 );
-			expect( screen.getByText( 'nested' ) ).toBeInTheDocument();
+			const inheriting = getScopingProvider(
+				screen.getByTestId( 'inheriting' )
+			);
+			const overriding = getScopingProvider(
+				screen.getByTestId( 'overriding' )
+			);
+
+			// A nested provider without its own `color` inherits the parent's.
+			expect( readProp( inheriting, ACCENT_RGB ) ).toBe( '255, 0, 0' );
+			// A nested provider with its own `color` overrides the parent's.
+			expect( readProp( overriding, ACCENT_RGB ) ).toBe( '0, 255, 0' );
 		} );
 	} );
 } );
-
-/* eslint-enable testing-library/no-container, testing-library/no-node-access */

From 1a4a177357016cbf9bdf2b6062788d90babd0fc0 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Fri, 12 Jun 2026 10:55:18 +0200
Subject: [PATCH 06/12] Theme: Assert the semantic brand token instead of the
 legacy one

Check `--wpds-color-bg-interactive-brand-strong` (a public design-system
token) rather than the legacy `--wp-admin-theme-color--rgb`. The default
seed resolves to the default brand color, and nesting is verified through
value relationships (inherit equals parent; override matches a standalone
provider of the same color).
---
 .../theme/src/test/theme-provider.test.tsx    | 82 ++++++++++++-------
 1 file changed, 51 insertions(+), 31 deletions(-)

diff --git a/packages/theme/src/test/theme-provider.test.tsx b/packages/theme/src/test/theme-provider.test.tsx
index c6e9be48dc54d0..cd7921a8bef303 100644
--- a/packages/theme/src/test/theme-provider.test.tsx
+++ b/packages/theme/src/test/theme-provider.test.tsx
@@ -5,6 +5,7 @@
 
 import { render, screen } from '@testing-library/react';
 import { ThemeProvider } from '../theme-provider';
+import { DEFAULT_SEED_COLORS } from '../color-ramps';
 
 // Mock the CSS module so the provider's scoping class is a real, stable class
 // name. Without this the global Jest CSS mock leaves the class `undefined`, and
@@ -13,9 +14,8 @@ jest.mock( '../style.module.css', () => ( {
 	root: 'theme-provider-root',
 } ) );
 
-// The legacy accent property is set to the seed color's sRGB channels, which
-// makes the expected value predictable regardless of color serialization.
-const ACCENT_RGB = '--wp-admin-theme-color--rgb';
+// A semantic design-system token derived from the `color.primary` seed.
+const BRAND_BG = '--wpds-color-bg-interactive-brand-strong';
 
 function readProp( element: Element, property: string ) {
 	return getComputedStyle( element ).getPropertyValue( property ).trim();
@@ -33,28 +33,31 @@ describe( 'ThemeProvider', () => {
 		expect( screen.getByText( 'content' ) ).toBeInTheDocument();
 	} );
 
-	it( 'defines the themed custom property within its subtree', () => {
+	it( 'defines the brand color token within its subtree', () => {
 		render(
-			<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
+			<ThemeProvider>
 				<div data-testid="child">x</div>
 			</ThemeProvider>
 		);
 
 		const provider = getScopingProvider( screen.getByTestId( 'child' ) );
-		expect( readProp( provider, ACCENT_RGB ) ).toBe( '255, 0, 0' );
+		// With no overrides, the brand background resolves to the default seed.
+		expect( readProp( provider, BRAND_BG ) ).toBe(
+			DEFAULT_SEED_COLORS.primary
+		);
 	} );
 
 	it( 'does not define the custom property outside of the provider', () => {
 		render(
-			<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
-				x
+			<ThemeProvider>
+				<div data-testid="child">x</div>
 			</ThemeProvider>
 		);
 
 		const outside = document.createElement( 'div' );
 		document.body.appendChild( outside );
 
-		expect( readProp( outside, ACCENT_RGB ) ).toBe( '' );
+		expect( readProp( outside, BRAND_BG ) ).toBe( '' );
 	} );
 
 	it( 'applies the cursor custom property when set', () => {
@@ -71,55 +74,72 @@ describe( 'ThemeProvider', () => {
 	} );
 
 	describe( 'isRoot', () => {
-		it( 'defines the custom property on the document root', () => {
+		it( 'defines the token on the document root', () => {
 			render(
-				<ThemeProvider isRoot color={ { primary: 'rgb(255, 0, 0)' } }>
-					x
+				<ThemeProvider isRoot>
+					<div>x</div>
 				</ThemeProvider>
 			);
 
-			expect( readProp( document.documentElement, ACCENT_RGB ) ).toBe(
-				'255, 0, 0'
+			expect( readProp( document.documentElement, BRAND_BG ) ).toBe(
+				DEFAULT_SEED_COLORS.primary
 			);
 		} );
 
 		it( 'does not affect the document root by default', () => {
 			render(
-				<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
-					x
+				<ThemeProvider>
+					<div>x</div>
 				</ThemeProvider>
 			);
 
-			expect( readProp( document.documentElement, ACCENT_RGB ) ).toBe(
-				''
-			);
+			expect( readProp( document.documentElement, BRAND_BG ) ).toBe( '' );
 		} );
 	} );
 
 	describe( 'nested providers', () => {
 		it( 'inherits the parent value, and a nested provider can override it', () => {
 			render(
-				<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
-					<ThemeProvider>
-						<div data-testid="inheriting">a</div>
+				<>
+					<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
+						<div data-testid="parent">p</div>
+						<ThemeProvider>
+							<div data-testid="inheriting">a</div>
+						</ThemeProvider>
+						<ThemeProvider color={ { primary: 'rgb(0, 255, 0)' } }>
+							<div data-testid="overriding">b</div>
+						</ThemeProvider>
 					</ThemeProvider>
 					<ThemeProvider color={ { primary: 'rgb(0, 255, 0)' } }>
-						<div data-testid="overriding">b</div>
+						<div data-testid="reference-green">g</div>
 					</ThemeProvider>
-				</ThemeProvider>
+				</>
 			);
 
-			const inheriting = getScopingProvider(
-				screen.getByTestId( 'inheriting' )
+			const parentValue = readProp(
+				getScopingProvider( screen.getByTestId( 'parent' ) ),
+				BRAND_BG
+			);
+			const inheritingValue = readProp(
+				getScopingProvider( screen.getByTestId( 'inheriting' ) ),
+				BRAND_BG
+			);
+			const overridingValue = readProp(
+				getScopingProvider( screen.getByTestId( 'overriding' ) ),
+				BRAND_BG
 			);
-			const overriding = getScopingProvider(
-				screen.getByTestId( 'overriding' )
+			const referenceGreenValue = readProp(
+				getScopingProvider( screen.getByTestId( 'reference-green' ) ),
+				BRAND_BG
 			);
 
 			// A nested provider without its own `color` inherits the parent's.
-			expect( readProp( inheriting, ACCENT_RGB ) ).toBe( '255, 0, 0' );
-			// A nested provider with its own `color` overrides the parent's.
-			expect( readProp( overriding, ACCENT_RGB ) ).toBe( '0, 255, 0' );
+			expect( inheritingValue ).toBe( parentValue );
+			// A nested provider with its own `color` overrides the parent's,
+			// resolving to the same value as a standalone provider seeded with
+			// that color.
+			expect( overridingValue ).not.toBe( parentValue );
+			expect( overridingValue ).toBe( referenceGreenValue );
 		} );
 	} );
 } );

From 9b6eacf5d56bf55cfd9f569bc795d427df7c9476 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Fri, 12 Jun 2026 10:57:54 +0200
Subject: [PATCH 07/12] Theme: Assert token equals the primary seed for
 in-gamut brand colors

Use mid-range seeds that round-trip through the brand ramp so the test can
assert exact `--wpds-color-bg-interactive-brand-strong === primary` equality,
including in the nested-override case.
---
 .../theme/src/test/theme-provider.test.tsx    | 73 ++++++++-----------
 1 file changed, 29 insertions(+), 44 deletions(-)

diff --git a/packages/theme/src/test/theme-provider.test.tsx b/packages/theme/src/test/theme-provider.test.tsx
index cd7921a8bef303..a12fba93d5328f 100644
--- a/packages/theme/src/test/theme-provider.test.tsx
+++ b/packages/theme/src/test/theme-provider.test.tsx
@@ -5,7 +5,6 @@
 
 import { render, screen } from '@testing-library/react';
 import { ThemeProvider } from '../theme-provider';
-import { DEFAULT_SEED_COLORS } from '../color-ramps';
 
 // Mock the CSS module so the provider's scoping class is a real, stable class
 // name. Without this the global Jest CSS mock leaves the class `undefined`, and
@@ -14,8 +13,13 @@ jest.mock( '../style.module.css', () => ( {
 	root: 'theme-provider-root',
 } ) );
 
-// A semantic design-system token derived from the `color.primary` seed.
+// The "strong" brand background resolves to the `color.primary` seed itself for
+// in-gamut brand colors, which makes the expected value predictable. (Extreme
+// seeds such as pure red or black get snapped into the accessible brand ramp, so
+// the seeds below are deliberately mid-range hex values that round-trip.)
 const BRAND_BG = '--wpds-color-bg-interactive-brand-strong';
+const PRIMARY = '#1e90ff';
+const OTHER_PRIMARY = '#8e44ad';
 
 function readProp( element: Element, property: string ) {
 	return getComputedStyle( element ).getPropertyValue( property ).trim();
@@ -33,23 +37,20 @@ describe( 'ThemeProvider', () => {
 		expect( screen.getByText( 'content' ) ).toBeInTheDocument();
 	} );
 
-	it( 'defines the brand color token within its subtree', () => {
+	it( 'defines the brand color token from the primary seed within its subtree', () => {
 		render(
-			<ThemeProvider>
+			<ThemeProvider color={ { primary: PRIMARY } }>
 				<div data-testid="child">x</div>
 			</ThemeProvider>
 		);
 
 		const provider = getScopingProvider( screen.getByTestId( 'child' ) );
-		// With no overrides, the brand background resolves to the default seed.
-		expect( readProp( provider, BRAND_BG ) ).toBe(
-			DEFAULT_SEED_COLORS.primary
-		);
+		expect( readProp( provider, BRAND_BG ) ).toBe( PRIMARY );
 	} );
 
 	it( 'does not define the custom property outside of the provider', () => {
 		render(
-			<ThemeProvider>
+			<ThemeProvider color={ { primary: PRIMARY } }>
 				<div data-testid="child">x</div>
 			</ThemeProvider>
 		);
@@ -76,19 +77,19 @@ describe( 'ThemeProvider', () => {
 	describe( 'isRoot', () => {
 		it( 'defines the token on the document root', () => {
 			render(
-				<ThemeProvider isRoot>
+				<ThemeProvider isRoot color={ { primary: PRIMARY } }>
 					<div>x</div>
 				</ThemeProvider>
 			);
 
 			expect( readProp( document.documentElement, BRAND_BG ) ).toBe(
-				DEFAULT_SEED_COLORS.primary
+				PRIMARY
 			);
 		} );
 
 		it( 'does not affect the document root by default', () => {
 			render(
-				<ThemeProvider>
+				<ThemeProvider color={ { primary: PRIMARY } }>
 					<div>x</div>
 				</ThemeProvider>
 			);
@@ -100,46 +101,30 @@ describe( 'ThemeProvider', () => {
 	describe( 'nested providers', () => {
 		it( 'inherits the parent value, and a nested provider can override it', () => {
 			render(
-				<>
-					<ThemeProvider color={ { primary: 'rgb(255, 0, 0)' } }>
-						<div data-testid="parent">p</div>
-						<ThemeProvider>
-							<div data-testid="inheriting">a</div>
-						</ThemeProvider>
-						<ThemeProvider color={ { primary: 'rgb(0, 255, 0)' } }>
-							<div data-testid="overriding">b</div>
-						</ThemeProvider>
+				<ThemeProvider color={ { primary: PRIMARY } }>
+					<div data-testid="parent">p</div>
+					<ThemeProvider>
+						<div data-testid="inheriting">a</div>
 					</ThemeProvider>
-					<ThemeProvider color={ { primary: 'rgb(0, 255, 0)' } }>
-						<div data-testid="reference-green">g</div>
+					<ThemeProvider color={ { primary: OTHER_PRIMARY } }>
+						<div data-testid="overriding">b</div>
 					</ThemeProvider>
-				</>
+				</ThemeProvider>
 			);
 
-			const parentValue = readProp(
-				getScopingProvider( screen.getByTestId( 'parent' ) ),
-				BRAND_BG
-			);
-			const inheritingValue = readProp(
-				getScopingProvider( screen.getByTestId( 'inheriting' ) ),
-				BRAND_BG
-			);
-			const overridingValue = readProp(
-				getScopingProvider( screen.getByTestId( 'overriding' ) ),
-				BRAND_BG
+			const parent = getScopingProvider( screen.getByTestId( 'parent' ) );
+			const inheriting = getScopingProvider(
+				screen.getByTestId( 'inheriting' )
 			);
-			const referenceGreenValue = readProp(
-				getScopingProvider( screen.getByTestId( 'reference-green' ) ),
-				BRAND_BG
+			const overriding = getScopingProvider(
+				screen.getByTestId( 'overriding' )
 			);
 
+			expect( readProp( parent, BRAND_BG ) ).toBe( PRIMARY );
 			// A nested provider without its own `color` inherits the parent's.
-			expect( inheritingValue ).toBe( parentValue );
-			// A nested provider with its own `color` overrides the parent's,
-			// resolving to the same value as a standalone provider seeded with
-			// that color.
-			expect( overridingValue ).not.toBe( parentValue );
-			expect( overridingValue ).toBe( referenceGreenValue );
+			expect( readProp( inheriting, BRAND_BG ) ).toBe( PRIMARY );
+			// A nested provider with its own `color` overrides the parent's.
+			expect( readProp( overriding, BRAND_BG ) ).toBe( OTHER_PRIMARY );
 		} );
 	} );
 } );

From b86c4d064b1d19f67e1422a02db681f5936e0252 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Fri, 12 Jun 2026 11:09:54 +0200
Subject: [PATCH 08/12] Theme: Cover the background color prop and partial
 overrides

Add a test for `color.background` (the only other settings prop), and tests for
partial overrides: a nested provider overriding `color.primary` still inherits
`color.background` and `cursor` from its parent.
---
 .../theme/src/test/theme-provider.test.tsx    | 60 +++++++++++++++++--
 1 file changed, 56 insertions(+), 4 deletions(-)

diff --git a/packages/theme/src/test/theme-provider.test.tsx b/packages/theme/src/test/theme-provider.test.tsx
index a12fba93d5328f..b0bc4c5168b5ec 100644
--- a/packages/theme/src/test/theme-provider.test.tsx
+++ b/packages/theme/src/test/theme-provider.test.tsx
@@ -13,13 +13,16 @@ jest.mock( '../style.module.css', () => ( {
 	root: 'theme-provider-root',
 } ) );
 
-// The "strong" brand background resolves to the `color.primary` seed itself for
-// in-gamut brand colors, which makes the expected value predictable. (Extreme
-// seeds such as pure red or black get snapped into the accessible brand ramp, so
-// the seeds below are deliberately mid-range hex values that round-trip.)
+// The "strong" brand background resolves to the `color.primary` seed itself, and
+// the neutral surface resolves to the `color.background` seed itself, which makes
+// the expected values predictable. (Extreme seeds get snapped into the accessible
+// ramp, so the seeds below are deliberately mid-range/light hex values that
+// round-trip. Ramp generation itself is covered by the color-ramps tests.)
 const BRAND_BG = '--wpds-color-bg-interactive-brand-strong';
+const SURFACE_BG = '--wpds-color-bg-surface-neutral';
 const PRIMARY = '#1e90ff';
 const OTHER_PRIMARY = '#8e44ad';
+const BACKGROUND = '#f8f8f8';
 
 function readProp( element: Element, property: string ) {
 	return getComputedStyle( element ).getPropertyValue( property ).trim();
@@ -48,6 +51,17 @@ describe( 'ThemeProvider', () => {
 		expect( readProp( provider, BRAND_BG ) ).toBe( PRIMARY );
 	} );
 
+	it( 'defines the surface color token from the background seed within its subtree', () => {
+		render(
+			<ThemeProvider color={ { background: BACKGROUND } }>
+				<div data-testid="child">x</div>
+			</ThemeProvider>
+		);
+
+		const provider = getScopingProvider( screen.getByTestId( 'child' ) );
+		expect( readProp( provider, SURFACE_BG ) ).toBe( BACKGROUND );
+	} );
+
 	it( 'does not define the custom property outside of the provider', () => {
 		render(
 			<ThemeProvider color={ { primary: PRIMARY } }>
@@ -126,5 +140,43 @@ describe( 'ThemeProvider', () => {
 			// A nested provider with its own `color` overrides the parent's.
 			expect( readProp( overriding, BRAND_BG ) ).toBe( OTHER_PRIMARY );
 		} );
+
+		it( 'overrides only the provided color, inheriting the rest', () => {
+			render(
+				<ThemeProvider
+					color={ { primary: PRIMARY, background: BACKGROUND } }
+				>
+					<ThemeProvider color={ { primary: OTHER_PRIMARY } }>
+						<div data-testid="child">c</div>
+					</ThemeProvider>
+				</ThemeProvider>
+			);
+
+			const child = getScopingProvider( screen.getByTestId( 'child' ) );
+			// `primary` is overridden by the nested provider...
+			expect( readProp( child, BRAND_BG ) ).toBe( OTHER_PRIMARY );
+			// ...while `background` keeps inheriting from the parent.
+			expect( readProp( child, SURFACE_BG ) ).toBe( BACKGROUND );
+		} );
+
+		it( 'inherits cursor while overriding color', () => {
+			render(
+				<ThemeProvider
+					color={ { primary: PRIMARY } }
+					cursor={ { control: 'pointer' } }
+				>
+					<ThemeProvider color={ { primary: OTHER_PRIMARY } }>
+						<div data-testid="child">c</div>
+					</ThemeProvider>
+				</ThemeProvider>
+			);
+
+			const child = getScopingProvider( screen.getByTestId( 'child' ) );
+			expect( readProp( child, BRAND_BG ) ).toBe( OTHER_PRIMARY );
+			// `cursor` is a separate settings group and keeps inheriting.
+			expect( readProp( child, '--wpds-cursor-control' ) ).toBe(
+				'pointer'
+			);
+		} );
 	} );
 } );

From 4110a90b5a23466ad63ff3983db9b8a15b772c47 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Fri, 12 Jun 2026 11:16:59 +0200
Subject: [PATCH 09/12] Theme: Refocus useThemeProviderStyles tests on its
 resolution contract

Scope the hook tests to what it uniquely owns: `resolvedSettings` resolution
precedence (local > inherited > default, resolved per-setting) and the legacy
`wp-admin` / `wp-components` bridge. Semantic `--wpds-*` token values stay
covered by the `ThemeProvider` tests, removing weak presence-only assertions.
---
 .../test/use-theme-provider-styles.test.tsx   | 164 ++++++++++--------
 1 file changed, 89 insertions(+), 75 deletions(-)

diff --git a/packages/theme/src/test/use-theme-provider-styles.test.tsx b/packages/theme/src/test/use-theme-provider-styles.test.tsx
index 567128e641ec75..1010b9e909d31d 100644
--- a/packages/theme/src/test/use-theme-provider-styles.test.tsx
+++ b/packages/theme/src/test/use-theme-provider-styles.test.tsx
@@ -1,3 +1,15 @@
+// `useThemeProviderStyles` is the resolution layer behind `ThemeProvider`. These
+// tests focus on what the hook uniquely owns:
+//
+// - `resolvedSettings`: how each setting is resolved (local prop > inherited from
+//   a parent provider > built-in default), which is the value propagated through
+//   context to descendant providers.
+// - the legacy `wp-admin` / `wp-components` bridge in `themeProviderStyles`, which
+//   the `ThemeProvider` tests intentionally do not cover.
+//
+// The resolved values of the semantic `--wpds-*` tokens are covered by the
+// `ThemeProvider` tests (which read them as computed CSS custom properties).
+
 import { renderHook } from '@testing-library/react';
 import { type ReactNode } from 'react';
 import { ThemeProvider } from '../theme-provider';
@@ -7,8 +19,8 @@ import { DEFAULT_SEED_COLORS } from '../color-ramps';
 type Styles = Record< string, string >;
 
 describe( 'useThemeProviderStyles', () => {
-	describe( 'defaults', () => {
-		it( 'resolves to the default seed colors when no settings are provided', () => {
+	describe( 'resolvedSettings', () => {
+		it( 'falls back to the default seed colors and no cursor', () => {
 			const { result } = renderHook( () => useThemeProviderStyles() );
 
 			expect( result.current.resolvedSettings.color ).toEqual( {
@@ -18,105 +30,107 @@ describe( 'useThemeProviderStyles', () => {
 			expect( result.current.resolvedSettings.cursor ).toBeUndefined();
 		} );
 
-		it( 'returns custom properties for the semantic and legacy tokens', () => {
-			const { result } = renderHook( () => useThemeProviderStyles() );
-			const styles = result.current.themeProviderStyles;
-
-			// Semantic design-system tokens.
-			expect( Object.keys( styles ) ).toEqual(
-				expect.arrayContaining( [
-					expect.stringMatching( /^--wpds-color-/ ),
-				] )
+		it( 'uses locally provided settings', () => {
+			const { result } = renderHook( () =>
+				useThemeProviderStyles( {
+					color: { primary: '#1e90ff', background: '#f8f8f8' },
+					cursor: { control: 'pointer' },
+				} )
 			);
-			// Legacy `wp-admin` / `wp-components` overrides.
-			expect( styles ).toHaveProperty( '--wp-admin-theme-color' );
-			expect( styles ).toHaveProperty( '--wp-components-color-accent' );
-		} );
 
-		it( 'does not set the cursor custom property', () => {
-			const { result } = renderHook( () => useThemeProviderStyles() );
+			expect( result.current.resolvedSettings ).toEqual( {
+				color: { primary: '#1e90ff', background: '#f8f8f8' },
+				cursor: { control: 'pointer' },
+			} );
+		} );
 
-			expect( result.current.themeProviderStyles ).not.toHaveProperty(
-				'--wpds-cursor-control'
+		describe( 'within a parent provider', () => {
+			const wrapper = ( { children }: { children: ReactNode } ) => (
+				<ThemeProvider
+					color={ { primary: '#abcdef', background: '#222222' } }
+					cursor={ { control: 'pointer' } }
+				>
+					{ children }
+				</ThemeProvider>
 			);
+
+			it( 'inherits every unset setting from the parent', () => {
+				const { result } = renderHook( () => useThemeProviderStyles(), {
+					wrapper,
+				} );
+
+				expect( result.current.resolvedSettings ).toEqual( {
+					color: { primary: '#abcdef', background: '#222222' },
+					cursor: { control: 'pointer' },
+				} );
+			} );
+
+			it( 'resolves each setting independently: local wins, unset inherits', () => {
+				const { result } = renderHook(
+					() =>
+						useThemeProviderStyles( {
+							color: { primary: '#00ff00' },
+						} ),
+					{ wrapper }
+				);
+
+				expect( result.current.resolvedSettings ).toEqual( {
+					// Provided locally.
+					color: { primary: '#00ff00', background: '#222222' },
+					// `background` and `cursor` keep inheriting from the parent.
+					cursor: { control: 'pointer' },
+				} );
+			} );
 		} );
 	} );
 
-	describe( 'explicit settings', () => {
-		it( 'uses the provided primary color', () => {
+	describe( 'legacy wp-admin / wp-components bridge', () => {
+		it( 'derives the wp-admin theme color from the primary seed', () => {
 			const { result } = renderHook( () =>
-				useThemeProviderStyles( { color: { primary: '#ff0000' } } )
+				useThemeProviderStyles( { color: { primary: '#1e90ff' } } )
 			);
+			const styles = result.current.themeProviderStyles as Styles;
 
-			expect( result.current.resolvedSettings.color?.primary ).toBe(
-				'#ff0000'
+			expect( styles[ '--wp-admin-theme-color' ] ).toBe( '#1e90ff' );
+			expect( styles[ '--wp-admin-theme-color--rgb' ] ).toBe(
+				'30, 144, 255'
 			);
-			// The background falls back to the default seed.
-			expect( result.current.resolvedSettings.color?.background ).toBe(
-				DEFAULT_SEED_COLORS.background
+		} );
+
+		it( 'aliases the wp-components colors onto the wp-admin and semantic tokens', () => {
+			const { result } = renderHook( () => useThemeProviderStyles() );
+			const styles = result.current.themeProviderStyles as Styles;
+
+			expect( styles[ '--wp-components-color-accent' ] ).toBe(
+				'var(--wp-admin-theme-color)'
+			);
+			expect( styles[ '--wp-components-color-accent-inverted' ] ).toBe(
+				'var(--wpds-color-fg-interactive-brand-strong)'
+			);
+			expect( styles[ '--wp-components-color-background' ] ).toBe(
+				'var(--wpds-color-bg-surface-neutral-strong)'
 			);
 		} );
+	} );
 
-		it( 'sets the cursor control custom property', () => {
+	describe( 'cursor', () => {
+		it( 'sets the cursor control custom property when provided', () => {
 			const { result } = renderHook( () =>
 				useThemeProviderStyles( { cursor: { control: 'pointer' } } )
 			);
 
-			expect( result.current.resolvedSettings.cursor ).toEqual( {
-				control: 'pointer',
-			} );
 			expect(
 				( result.current.themeProviderStyles as Styles )[
 					'--wpds-cursor-control'
 				]
 			).toBe( 'pointer' );
 		} );
-	} );
-
-	describe( 'inheritance from a parent provider', () => {
-		const wrapper = ( { children }: { children: ReactNode } ) => (
-			<ThemeProvider
-				color={ { primary: '#abcdef', background: '#222222' } }
-				cursor={ { control: 'pointer' } }
-			>
-				{ children }
-			</ThemeProvider>
-		);
-
-		it( 'inherits color and cursor settings when none are provided locally', () => {
-			const { result } = renderHook( () => useThemeProviderStyles(), {
-				wrapper,
-			} );
-
-			expect( result.current.resolvedSettings.color ).toEqual( {
-				primary: '#abcdef',
-				background: '#222222',
-			} );
-			expect( result.current.resolvedSettings.cursor ).toEqual( {
-				control: 'pointer',
-			} );
-		} );
 
-		it( 'lets local settings override the inherited ones', () => {
-			const { result } = renderHook(
-				() =>
-					useThemeProviderStyles( {
-						color: { primary: '#00ff00' },
-						cursor: { control: 'default' },
-					} ),
-				{ wrapper }
-			);
+		it( 'omits the cursor control custom property by default', () => {
+			const { result } = renderHook( () => useThemeProviderStyles() );
 
-			// Locally provided values win.
-			expect( result.current.resolvedSettings.color?.primary ).toBe(
-				'#00ff00'
-			);
-			expect( result.current.resolvedSettings.cursor ).toEqual( {
-				control: 'default',
-			} );
-			// Values not provided locally keep inheriting from the parent.
-			expect( result.current.resolvedSettings.color?.background ).toBe(
-				'#222222'
+			expect( result.current.themeProviderStyles ).not.toHaveProperty(
+				'--wpds-cursor-control'
 			);
 		} );
 	} );

From d0ca31891919512e74482f5b7d77600dca192626 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Mon, 15 Jun 2026 15:39:06 +0200
Subject: [PATCH 10/12] Theme: Consolidate ThemeProvider color and nesting
 tests

Address review feedback: merge the separate brand/surface token tests into one
"defines the color tokens from the seeds" test, and collapse the nested-provider
tests into a single "overrides the settings it defines and inherits the rest"
case covering both full inheritance and partial override.

Also adapt the token names to trunk's `bg`/`fg` -> `background`/`foreground`
rename (#79098).
---
 .../theme/src/test/theme-provider.test.tsx    | 83 +++++--------------
 1 file changed, 21 insertions(+), 62 deletions(-)

diff --git a/packages/theme/src/test/theme-provider.test.tsx b/packages/theme/src/test/theme-provider.test.tsx
index b0bc4c5168b5ec..6d633c6c2097af 100644
--- a/packages/theme/src/test/theme-provider.test.tsx
+++ b/packages/theme/src/test/theme-provider.test.tsx
@@ -18,8 +18,9 @@ jest.mock( '../style.module.css', () => ( {
 // the expected values predictable. (Extreme seeds get snapped into the accessible
 // ramp, so the seeds below are deliberately mid-range/light hex values that
 // round-trip. Ramp generation itself is covered by the color-ramps tests.)
-const BRAND_BG = '--wpds-color-bg-interactive-brand-strong';
-const SURFACE_BG = '--wpds-color-bg-surface-neutral';
+const BRAND_BG = '--wpds-color-background-interactive-brand-strong';
+const SURFACE_BG = '--wpds-color-background-surface-neutral';
+const CURSOR_CONTROL = '--wpds-cursor-control';
 const PRIMARY = '#1e90ff';
 const OTHER_PRIMARY = '#8e44ad';
 const BACKGROUND = '#f8f8f8';
@@ -40,25 +41,17 @@ describe( 'ThemeProvider', () => {
 		expect( screen.getByText( 'content' ) ).toBeInTheDocument();
 	} );
 
-	it( 'defines the brand color token from the primary seed within its subtree', () => {
+	it( 'defines the color tokens from the seeds within its subtree', () => {
 		render(
-			<ThemeProvider color={ { primary: PRIMARY } }>
+			<ThemeProvider
+				color={ { primary: PRIMARY, background: BACKGROUND } }
+			>
 				<div data-testid="child">x</div>
 			</ThemeProvider>
 		);
 
 		const provider = getScopingProvider( screen.getByTestId( 'child' ) );
 		expect( readProp( provider, BRAND_BG ) ).toBe( PRIMARY );
-	} );
-
-	it( 'defines the surface color token from the background seed within its subtree', () => {
-		render(
-			<ThemeProvider color={ { background: BACKGROUND } }>
-				<div data-testid="child">x</div>
-			</ThemeProvider>
-		);
-
-		const provider = getScopingProvider( screen.getByTestId( 'child' ) );
 		expect( readProp( provider, SURFACE_BG ) ).toBe( BACKGROUND );
 	} );
 
@@ -83,9 +76,7 @@ describe( 'ThemeProvider', () => {
 		);
 
 		const provider = getScopingProvider( screen.getByTestId( 'child' ) );
-		expect( readProp( provider, '--wpds-cursor-control' ) ).toBe(
-			'pointer'
-		);
+		expect( readProp( provider, CURSOR_CONTROL ) ).toBe( 'pointer' );
 	} );
 
 	describe( 'isRoot', () => {
@@ -113,10 +104,12 @@ describe( 'ThemeProvider', () => {
 	} );
 
 	describe( 'nested providers', () => {
-		it( 'inherits the parent value, and a nested provider can override it', () => {
+		it( 'overrides the settings it defines and inherits the rest', () => {
 			render(
-				<ThemeProvider color={ { primary: PRIMARY } }>
-					<div data-testid="parent">p</div>
+				<ThemeProvider
+					color={ { primary: PRIMARY, background: BACKGROUND } }
+					cursor={ { control: 'pointer' } }
+				>
 					<ThemeProvider>
 						<div data-testid="inheriting">a</div>
 					</ThemeProvider>
@@ -126,7 +119,6 @@ describe( 'ThemeProvider', () => {
 				</ThemeProvider>
 			);
 
-			const parent = getScopingProvider( screen.getByTestId( 'parent' ) );
 			const inheriting = getScopingProvider(
 				screen.getByTestId( 'inheriting' )
 			);
@@ -134,49 +126,16 @@ describe( 'ThemeProvider', () => {
 				screen.getByTestId( 'overriding' )
 			);
 
-			expect( readProp( parent, BRAND_BG ) ).toBe( PRIMARY );
-			// A nested provider without its own `color` inherits the parent's.
+			// A nested provider with no settings of its own inherits everything.
 			expect( readProp( inheriting, BRAND_BG ) ).toBe( PRIMARY );
-			// A nested provider with its own `color` overrides the parent's.
-			expect( readProp( overriding, BRAND_BG ) ).toBe( OTHER_PRIMARY );
-		} );
+			expect( readProp( inheriting, SURFACE_BG ) ).toBe( BACKGROUND );
+			expect( readProp( inheriting, CURSOR_CONTROL ) ).toBe( 'pointer' );
 
-		it( 'overrides only the provided color, inheriting the rest', () => {
-			render(
-				<ThemeProvider
-					color={ { primary: PRIMARY, background: BACKGROUND } }
-				>
-					<ThemeProvider color={ { primary: OTHER_PRIMARY } }>
-						<div data-testid="child">c</div>
-					</ThemeProvider>
-				</ThemeProvider>
-			);
-
-			const child = getScopingProvider( screen.getByTestId( 'child' ) );
-			// `primary` is overridden by the nested provider...
-			expect( readProp( child, BRAND_BG ) ).toBe( OTHER_PRIMARY );
-			// ...while `background` keeps inheriting from the parent.
-			expect( readProp( child, SURFACE_BG ) ).toBe( BACKGROUND );
-		} );
-
-		it( 'inherits cursor while overriding color', () => {
-			render(
-				<ThemeProvider
-					color={ { primary: PRIMARY } }
-					cursor={ { control: 'pointer' } }
-				>
-					<ThemeProvider color={ { primary: OTHER_PRIMARY } }>
-						<div data-testid="child">c</div>
-					</ThemeProvider>
-				</ThemeProvider>
-			);
-
-			const child = getScopingProvider( screen.getByTestId( 'child' ) );
-			expect( readProp( child, BRAND_BG ) ).toBe( OTHER_PRIMARY );
-			// `cursor` is a separate settings group and keeps inheriting.
-			expect( readProp( child, '--wpds-cursor-control' ) ).toBe(
-				'pointer'
-			);
+			// A nested provider overrides only what it defines (`primary`),
+			// inheriting the rest (`background`, `cursor`).
+			expect( readProp( overriding, BRAND_BG ) ).toBe( OTHER_PRIMARY );
+			expect( readProp( overriding, SURFACE_BG ) ).toBe( BACKGROUND );
+			expect( readProp( overriding, CURSOR_CONTROL ) ).toBe( 'pointer' );
 		} );
 	} );
 } );

From 6b0eb0e56c053775132d2e5d0c9b404b48b0a6f9 Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Mon, 15 Jun 2026 15:39:09 +0200
Subject: [PATCH 11/12] Theme: Use CSSProperties type in useThemeProviderStyles
 tests

Address review feedback: drop the custom `Record< string, string >` style type
and read the hook's `CSSProperties` return value directly (custom properties are
typed via the `react-css-custom-properties` augmentation).

Also adapt to trunk: update the legacy `wp-components` alias targets for the
`bg`/`fg` -> `background`/`foreground` rename (#79098), and assert the `color`
and `cursor` settings explicitly so the new `cornerRadius` field does not couple
these tests to an unrelated default.
---
 .../test/use-theme-provider-styles.test.tsx   | 44 +++++++++++--------
 1 file changed, 25 insertions(+), 19 deletions(-)

diff --git a/packages/theme/src/test/use-theme-provider-styles.test.tsx b/packages/theme/src/test/use-theme-provider-styles.test.tsx
index 1010b9e909d31d..27739345c72130 100644
--- a/packages/theme/src/test/use-theme-provider-styles.test.tsx
+++ b/packages/theme/src/test/use-theme-provider-styles.test.tsx
@@ -16,8 +16,6 @@ import { ThemeProvider } from '../theme-provider';
 import { useThemeProviderStyles } from '../use-theme-provider-styles';
 import { DEFAULT_SEED_COLORS } from '../color-ramps';
 
-type Styles = Record< string, string >;
-
 describe( 'useThemeProviderStyles', () => {
 	describe( 'resolvedSettings', () => {
 		it( 'falls back to the default seed colors and no cursor', () => {
@@ -38,9 +36,12 @@ describe( 'useThemeProviderStyles', () => {
 				} )
 			);
 
-			expect( result.current.resolvedSettings ).toEqual( {
-				color: { primary: '#1e90ff', background: '#f8f8f8' },
-				cursor: { control: 'pointer' },
+			expect( result.current.resolvedSettings.color ).toEqual( {
+				primary: '#1e90ff',
+				background: '#f8f8f8',
+			} );
+			expect( result.current.resolvedSettings.cursor ).toEqual( {
+				control: 'pointer',
 			} );
 		} );
 
@@ -59,9 +60,12 @@ describe( 'useThemeProviderStyles', () => {
 					wrapper,
 				} );
 
-				expect( result.current.resolvedSettings ).toEqual( {
-					color: { primary: '#abcdef', background: '#222222' },
-					cursor: { control: 'pointer' },
+				expect( result.current.resolvedSettings.color ).toEqual( {
+					primary: '#abcdef',
+					background: '#222222',
+				} );
+				expect( result.current.resolvedSettings.cursor ).toEqual( {
+					control: 'pointer',
 				} );
 			} );
 
@@ -74,11 +78,15 @@ describe( 'useThemeProviderStyles', () => {
 					{ wrapper }
 				);
 
-				expect( result.current.resolvedSettings ).toEqual( {
+				expect( result.current.resolvedSettings.color ).toEqual( {
 					// Provided locally.
-					color: { primary: '#00ff00', background: '#222222' },
-					// `background` and `cursor` keep inheriting from the parent.
-					cursor: { control: 'pointer' },
+					primary: '#00ff00',
+					// `background` keeps inheriting from the parent.
+					background: '#222222',
+				} );
+				// `cursor` keeps inheriting from the parent.
+				expect( result.current.resolvedSettings.cursor ).toEqual( {
+					control: 'pointer',
 				} );
 			} );
 		} );
@@ -89,7 +97,7 @@ describe( 'useThemeProviderStyles', () => {
 			const { result } = renderHook( () =>
 				useThemeProviderStyles( { color: { primary: '#1e90ff' } } )
 			);
-			const styles = result.current.themeProviderStyles as Styles;
+			const styles = result.current.themeProviderStyles;
 
 			expect( styles[ '--wp-admin-theme-color' ] ).toBe( '#1e90ff' );
 			expect( styles[ '--wp-admin-theme-color--rgb' ] ).toBe(
@@ -99,16 +107,16 @@ describe( 'useThemeProviderStyles', () => {
 
 		it( 'aliases the wp-components colors onto the wp-admin and semantic tokens', () => {
 			const { result } = renderHook( () => useThemeProviderStyles() );
-			const styles = result.current.themeProviderStyles as Styles;
+			const styles = result.current.themeProviderStyles;
 
 			expect( styles[ '--wp-components-color-accent' ] ).toBe(
 				'var(--wp-admin-theme-color)'
 			);
 			expect( styles[ '--wp-components-color-accent-inverted' ] ).toBe(
-				'var(--wpds-color-fg-interactive-brand-strong)'
+				'var(--wpds-color-foreground-interactive-brand-strong)'
 			);
 			expect( styles[ '--wp-components-color-background' ] ).toBe(
-				'var(--wpds-color-bg-surface-neutral-strong)'
+				'var(--wpds-color-background-surface-neutral-strong)'
 			);
 		} );
 	} );
@@ -120,9 +128,7 @@ describe( 'useThemeProviderStyles', () => {
 			);
 
 			expect(
-				( result.current.themeProviderStyles as Styles )[
-					'--wpds-cursor-control'
-				]
+				result.current.themeProviderStyles[ '--wpds-cursor-control' ]
 			).toBe( 'pointer' );
 		} );
 

From dc8ee0553b4890dd37904971f1fb938d785c8a7d Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Mon, 15 Jun 2026 15:44:00 +0200
Subject: [PATCH 12/12] Theme: Add cornerRadius coverage to ThemeProvider tests

`cornerRadius` is a public ThemeProvider setting with the same prop > inherited
> default resolution as color/cursor, but was untested. Assert the rendered
`data-wpds-corner-radius` attribute (explicit, default, inherited across
nesting) and the resolved `cornerRadius` setting in the hook.
---
 .../theme/src/test/theme-provider.test.tsx    | 37 ++++++++++++++++++-
 .../test/use-theme-provider-styles.test.tsx   | 17 ++++++++-
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/packages/theme/src/test/theme-provider.test.tsx b/packages/theme/src/test/theme-provider.test.tsx
index 6d633c6c2097af..37e410d717494b 100644
--- a/packages/theme/src/test/theme-provider.test.tsx
+++ b/packages/theme/src/test/theme-provider.test.tsx
@@ -79,6 +79,32 @@ describe( 'ThemeProvider', () => {
 		expect( readProp( provider, CURSOR_CONTROL ) ).toBe( 'pointer' );
 	} );
 
+	describe( 'cornerRadius', () => {
+		it( 'reflects the preset as a data attribute', () => {
+			render(
+				<ThemeProvider cornerRadius="pronounced">
+					<div data-testid="child">x</div>
+				</ThemeProvider>
+			);
+
+			expect(
+				getScopingProvider( screen.getByTestId( 'child' ) )
+			).toHaveAttribute( 'data-wpds-corner-radius', 'pronounced' );
+		} );
+
+		it( 'defaults to the subtle preset', () => {
+			render(
+				<ThemeProvider>
+					<div data-testid="child">x</div>
+				</ThemeProvider>
+			);
+
+			expect(
+				getScopingProvider( screen.getByTestId( 'child' ) )
+			).toHaveAttribute( 'data-wpds-corner-radius', 'subtle' );
+		} );
+	} );
+
 	describe( 'isRoot', () => {
 		it( 'defines the token on the document root', () => {
 			render(
@@ -109,6 +135,7 @@ describe( 'ThemeProvider', () => {
 				<ThemeProvider
 					color={ { primary: PRIMARY, background: BACKGROUND } }
 					cursor={ { control: 'pointer' } }
+					cornerRadius="pronounced"
 				>
 					<ThemeProvider>
 						<div data-testid="inheriting">a</div>
@@ -130,12 +157,20 @@ describe( 'ThemeProvider', () => {
 			expect( readProp( inheriting, BRAND_BG ) ).toBe( PRIMARY );
 			expect( readProp( inheriting, SURFACE_BG ) ).toBe( BACKGROUND );
 			expect( readProp( inheriting, CURSOR_CONTROL ) ).toBe( 'pointer' );
+			expect( inheriting ).toHaveAttribute(
+				'data-wpds-corner-radius',
+				'pronounced'
+			);
 
 			// A nested provider overrides only what it defines (`primary`),
-			// inheriting the rest (`background`, `cursor`).
+			// inheriting the rest (`background`, `cursor`, `cornerRadius`).
 			expect( readProp( overriding, BRAND_BG ) ).toBe( OTHER_PRIMARY );
 			expect( readProp( overriding, SURFACE_BG ) ).toBe( BACKGROUND );
 			expect( readProp( overriding, CURSOR_CONTROL ) ).toBe( 'pointer' );
+			expect( overriding ).toHaveAttribute(
+				'data-wpds-corner-radius',
+				'pronounced'
+			);
 		} );
 	} );
 } );
diff --git a/packages/theme/src/test/use-theme-provider-styles.test.tsx b/packages/theme/src/test/use-theme-provider-styles.test.tsx
index 27739345c72130..bc861263f311fe 100644
--- a/packages/theme/src/test/use-theme-provider-styles.test.tsx
+++ b/packages/theme/src/test/use-theme-provider-styles.test.tsx
@@ -26,6 +26,10 @@ describe( 'useThemeProviderStyles', () => {
 				background: DEFAULT_SEED_COLORS.background,
 			} );
 			expect( result.current.resolvedSettings.cursor ).toBeUndefined();
+			// `cornerRadius` falls back to the prebuilt default.
+			expect( result.current.resolvedSettings.cornerRadius ).toBe(
+				'subtle'
+			);
 		} );
 
 		it( 'uses locally provided settings', () => {
@@ -33,6 +37,7 @@ describe( 'useThemeProviderStyles', () => {
 				useThemeProviderStyles( {
 					color: { primary: '#1e90ff', background: '#f8f8f8' },
 					cursor: { control: 'pointer' },
+					cornerRadius: 'moderate',
 				} )
 			);
 
@@ -43,6 +48,9 @@ describe( 'useThemeProviderStyles', () => {
 			expect( result.current.resolvedSettings.cursor ).toEqual( {
 				control: 'pointer',
 			} );
+			expect( result.current.resolvedSettings.cornerRadius ).toBe(
+				'moderate'
+			);
 		} );
 
 		describe( 'within a parent provider', () => {
@@ -50,6 +58,7 @@ describe( 'useThemeProviderStyles', () => {
 				<ThemeProvider
 					color={ { primary: '#abcdef', background: '#222222' } }
 					cursor={ { control: 'pointer' } }
+					cornerRadius="pronounced"
 				>
 					{ children }
 				</ThemeProvider>
@@ -67,6 +76,9 @@ describe( 'useThemeProviderStyles', () => {
 				expect( result.current.resolvedSettings.cursor ).toEqual( {
 					control: 'pointer',
 				} );
+				expect( result.current.resolvedSettings.cornerRadius ).toBe(
+					'pronounced'
+				);
 			} );
 
 			it( 'resolves each setting independently: local wins, unset inherits', () => {
@@ -84,10 +96,13 @@ describe( 'useThemeProviderStyles', () => {
 					// `background` keeps inheriting from the parent.
 					background: '#222222',
 				} );
-				// `cursor` keeps inheriting from the parent.
+				// `cursor` and `cornerRadius` keep inheriting from the parent.
 				expect( result.current.resolvedSettings.cursor ).toEqual( {
 					control: 'pointer',
 				} );
+				expect( result.current.resolvedSettings.cornerRadius ).toBe(
+					'pronounced'
+				);
 			} );
 		} );
 	} );