From 956bf404b545680f77b10fe8c2539a8572e8f578 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Wed, 25 Feb 2026 01:40:26 +0900
Subject: [PATCH 1/2] Dialog: Add legacy z-index compatibility

---
 packages/ui/src/dialog/stories/index.story.tsx | 14 ++++++++++++++
 packages/ui/src/dialog/style.module.css        |  2 ++
 2 files changed, 16 insertions(+)

diff --git a/packages/ui/src/dialog/stories/index.story.tsx b/packages/ui/src/dialog/stories/index.story.tsx
index f2af5aa127d359..e70362f0241b77 100644
--- a/packages/ui/src/dialog/stories/index.story.tsx
+++ b/packages/ui/src/dialog/stories/index.story.tsx
@@ -175,3 +175,17 @@ export const AllSizes: Story = {
 		children: <SizePlaygroundContent />,
 	},
 };
+
+/**
+ * Popovers in Gutenberg are managed with explicit z-index values, which can create
+ * situations where a dialog renders below another popover, when you want it to be rendered above.
+ *
+ * The `--wp-ui-dialog-z-index` CSS variable controls the z-index of both the
+ * backdrop and the popup. It can be overridden globally by setting the variable
+ * on `:root` or `body`. (This story doesn't actually demonstrate the feature
+ * because it requires a global CSS rule.)
+ */
+export const WithCustomZIndex: Story = {
+	..._Default,
+	name: 'With Custom z-index',
+};
diff --git a/packages/ui/src/dialog/style.module.css b/packages/ui/src/dialog/style.module.css
index 759da730c20e16..c8de96078d8d69 100644
--- a/packages/ui/src/dialog/style.module.css
+++ b/packages/ui/src/dialog/style.module.css
@@ -4,6 +4,7 @@
 	.backdrop {
 		position: fixed;
 		inset: 0;
+		z-index: var(--wp-ui-dialog-z-index, initial);
 		background-color: rgba(0, 0, 0, 0.35);
 
 		&[data-starting-style],
@@ -25,6 +26,7 @@
 		top: 50%;
 		/* stylelint-disable-next-line plugin/use-logical-properties-and-values -- Physical centering technique used with transform: translate(-50%, -50%) */
 		left: 50%;
+		z-index: var(--wp-ui-dialog-z-index, initial);
 		transform: translate(-50%, -50%);
 		box-sizing: border-box;
 		min-width: 320px;

From 15b8b2e3d450ed5a5a5159fa64ccfd822c661d85 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Wed, 25 Feb 2026 02:05:29 +0900
Subject: [PATCH 2/2] Add changelog

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

diff --git a/packages/ui/CHANGELOG.md b/packages/ui/CHANGELOG.md
index 90a9ba497407c0..50ad0f459e47ea 100644
--- a/packages/ui/CHANGELOG.md
+++ b/packages/ui/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Enhancements
+
+-   `Dialog`: Add `--wp-ui-dialog-z-index` CSS custom property for legacy z-index compatibility ([#75874](https://github.com/WordPress/gutenberg/pull/75874)).
+
 ### Bug Fixes
 
 -   `IconButton`: Hide tooltip when the button is truly disabled ([#75754](https://github.com/WordPress/gutenberg/pull/75754)).