Dialog: Add legacy z-index compatibility

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)).

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',
+};

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;