From 6de89a9201a6a998823f17860661e17893c92387 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Wed, 1 Jul 2026 19:34:23 +0200 Subject: [PATCH 1/3] ThemeProvider: Document wrapper customization scope --- packages/theme/README.md | 2 ++ packages/theme/src/types.ts | 7 +++++++ 2 files changed, 9 insertions(+) diff --git a/packages/theme/README.md b/packages/theme/README.md index 541cfa80be51d1..e5dec026835504 100644 --- a/packages/theme/README.md +++ b/packages/theme/README.md @@ -89,6 +89,8 @@ The `cornerRadius` prop sets the overall roundness preset for the theme subtree. When the `color`, `cursor`, or `cornerRadius` prop is omitted, the theme inherits the value from the closest parent `ThemeProvider`, or uses the default value if none is inherited. +The provider's wrapper element is an implementation detail. `ThemeProvider` does not accept wrapper customization props such as `className`, `style`, `as`, `render`, or `ref`. Its wrapper currently uses `display: contents` so it can scope CSS custom properties without adding layout, making element-level customization misleading. + ### Nesting Providers The provider can be used recursively to override or modify the theme for a specific subtree. diff --git a/packages/theme/src/types.ts b/packages/theme/src/types.ts index 3a68f28e6ebc10..cb92b738a11bab 100644 --- a/packages/theme/src/types.ts +++ b/packages/theme/src/types.ts @@ -59,6 +59,13 @@ export interface ThemeProviderSettings { cornerRadius?: CornerRadiusPreset; } +/** + * Props for the `ThemeProvider` component. + * + * The provider's wrapper element is intentionally not customizable and does + * not accept props such as `className`, `style`, `as`, `render`, or `ref`. + * The wrapper is an implementation detail used to scope CSS custom properties. + */ export interface ThemeProviderProps extends ThemeProviderSettings { /** * The children to render. From 6cc4f10a176d9b113074254428f52e6510e2cbf0 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Wed, 1 Jul 2026 19:35:42 +0200 Subject: [PATCH 2/3] ThemeProvider: Add wrapper scope changelog entry --- packages/theme/CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/theme/CHANGELOG.md b/packages/theme/CHANGELOG.md index a7e4bb97c276ff..a8b7e617759f78 100644 --- a/packages/theme/CHANGELOG.md +++ b/packages/theme/CHANGELOG.md @@ -10,6 +10,10 @@ - Mark the published `design-tokens.css` file as side-effectful so downstream bundlers preserve the documented CSS import ([#79551](https://github.com/WordPress/gutenberg/pull/79551)). +### Documentation + +- Document that `ThemeProvider` does not accept wrapper customization props ([#79763](https://github.com/WordPress/gutenberg/pull/79763)). + ## 0.17.0 (2026-06-30) ### Breaking Changes From 2566c5337fc6c863c3be6339af0e4e577249810c Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Wed, 1 Jul 2026 19:50:13 +0200 Subject: [PATCH 3/3] ThemeProvider: Refine wrapper scope docs --- packages/theme/README.md | 2 +- packages/theme/src/types.ts | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/theme/README.md b/packages/theme/README.md index e5dec026835504..9b2afa1dfc3496 100644 --- a/packages/theme/README.md +++ b/packages/theme/README.md @@ -89,7 +89,7 @@ The `cornerRadius` prop sets the overall roundness preset for the theme subtree. When the `color`, `cursor`, or `cornerRadius` prop is omitted, the theme inherits the value from the closest parent `ThemeProvider`, or uses the default value if none is inherited. -The provider's wrapper element is an implementation detail. `ThemeProvider` does not accept wrapper customization props such as `className`, `style`, `as`, `render`, or `ref`. Its wrapper currently uses `display: contents` so it can scope CSS custom properties without adding layout, making element-level customization misleading. +`ThemeProvider` does not accept wrapper customization props such as `className`, `style`, `as`, `render`, or `ref`. ### Nesting Providers diff --git a/packages/theme/src/types.ts b/packages/theme/src/types.ts index cb92b738a11bab..e8107fb8b22451 100644 --- a/packages/theme/src/types.ts +++ b/packages/theme/src/types.ts @@ -64,7 +64,6 @@ export interface ThemeProviderSettings { * * The provider's wrapper element is intentionally not customizable and does * not accept props such as `className`, `style`, `as`, `render`, or `ref`. - * The wrapper is an implementation detail used to scope CSS custom properties. */ export interface ThemeProviderProps extends ThemeProviderSettings { /**