Document our z-index values

Fixes #18532

diff --git a/docs/layout/overview.md b/docs/layout/overview.md
index 3e6c7e7e05ca676fd54e61a68952a15ab6d89d13..5b5ceb16cb517c9585dd4714eec17e51a72736fb 100644 (file)
--- a/docs/layout/overview.md
+++ b/docs/layout/overview.md
@@ -155,3 +155,23 @@ The Sass mixin for the above example look like that shown beneath:
 {% highlight scss %}
 @include media-breakpoint-between(md, lg) { ... }
 {% endhighlight %}
+
+## Z-index
+
+Several Bootstrap components utilize `z-index`, the CSS property that helps control layout by providing a third axis to arrange content. We utilize a default z-index scale in Bootstrap that's been designed to properly layer navigation, tooltips and popovers, modals, and more.
+
+We don't encourage customization of these values; should you change one, you likely need to change them all.
+
+```scss
+$zindex-dropdown-backdrop:  990 !default;
+$zindex-navbar:            1000 !default;
+$zindex-dropdown:          1000 !default;
+$zindex-popover:           1060 !default;
+$zindex-tooltip:           1070 !default;
+$zindex-navbar-fixed:      1030 !default;
+$zindex-navbar-sticky:     1030 !default;
+$zindex-modal-bg:          1040 !default;
+$zindex-modal:             1050 !default;
+```
+
+Background elements—like the backdrops that allow click-dismissing—tend to reside on a lower `z-index`s, while navigation and popovers utilize higher `z-index`s to ensure they overlay surrounding content.