From ae303c4a05be72a89b7a8b41736bf9da75c245a7 Mon Sep 17 00:00:00 2001
From: lazerg <lazerg2@gmail.com>
Date: Tue, 28 Jul 2026 15:22:03 +0500
Subject: [PATCH] docs: document overlay stacking change in v21 update guide

---
 adev/src/app/features/update/recommendations.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/adev/src/app/features/update/recommendations.ts b/adev/src/app/features/update/recommendations.ts
index ee3ef33c122..24b976702cf 100644
--- a/adev/src/app/features/update/recommendations.ts
+++ b/adev/src/app/features/update/recommendations.ts
@@ -2781,6 +2781,15 @@ export const RECOMMENDATIONS: Step[] = [
     step: 'update @angular/material',
     action: 'Run `ng update @angular/material@21`.',
   },
+  {
+    possibleIn: 2100,
+    necessaryAsOf: 2100,
+    level: ApplicationComplexity.Medium,
+    material: true,
+    step: '21.0.0-cdk-overlay-top-layer-stacking',
+    action:
+      "CDK overlays can now render in the browser's native top layer, causing elements that previously appeared above Material overlays via `z-index` to render beneath them. You can restore the previous behavior by providing `OVERLAY_DEFAULT_CONFIG` from `@angular/cdk/overlay` with the value `{usePopover: false}`.",
+  },
   {
     possibleIn: 2100,
     necessaryAsOf: 2100,