Merge branch 'v4-dev' of github.com:twbs/bootstrap into v4-dev

2 files changed, 62 insertions, 2 deletions

diff --git a/docs/layout/flexbox-grid.md b/docs/layout/flexbox-grid.md
index 80db93c93..a26314cd6 100644
--- a/docs/layout/flexbox-grid.md
+++ b/docs/layout/flexbox-grid.md
@@ -26,13 +26,18 @@ The flexbox grid system behaves similar to our default grid system, but with a f
 - Nesting, offsets, pushes, and pulls are all supported in the flexbox grid system.
 - Flexbox grid columns without a set width will automatically layout with equal widths. For example, four columns will each automatically be 25% wide.
 - Flexbox grid columns have significantly more alignment options available, including vertical alignment.
-- Unlike the default grid system where a grid column starts as full-width in the `xs` tier, flexbox requires a `.col-{breakpoint}` class for each tier.
+- Unlike the default grid system where a grid column starts as full-width in the `xs` tier, **flexbox requires a `.col-{breakpoint}` class for each tier.**
+- Be aware of the limitations and [bugs around flexbox](https://github.com/philipwalton/flexbugs), like the [inability to use some HTML elements as flex containers](https://github.com/philipwalton/flexbugs#9-some-html-elements-cant-be-flex-containers).
 
 Chill? Awesome—keep reading for more information and some code snippets.
 
 ## Auto-layout columns
 
-When flexbox support is enabled, you can utilize breakpoint-specific column classes for equal-width columns. Add any number of `.col-{breakpoint}`s for each breakpoint you need and you're good to go. For example, here's are two grid layouts that apply to every device and viewport possible.
+When flexbox support is enabled, you can utilize breakpoint-specific column classes for equal-width columns. Add any number of `.col-{breakpoint}`s for each breakpoint you need and every column will be the same width.
+
+### Equal-width
+
+For example, here are two grid layouts that apply to every device and viewport, from `xs` to `xl`.
 
 <div class="bd-example-row">
 {% example html %}
@@ -60,6 +65,8 @@ When flexbox support is enabled, you can utilize breakpoint-specific column clas
 {% endexample %}
 </div>
 
+### Setting one column width
+
 Auto-layout for flexbox grid columns also means you can set the width of one column and the others will automatically resize around it. You may use predefined grid classes (as shown below), grid mixins, or inline widths. Note that the other columns will resize no matter the width of the center column.
 
 <div class="bd-example-row">
@@ -91,6 +98,39 @@ Auto-layout for flexbox grid columns also means you can set the width of one col
 {% endexample %}
 </div>
 
+### Variable width content
+
+Using the `col-{breakpoint}-auto` classes, columns can size itself based on the natural width of its content. This is super handy with single line content like inputs, numbers, etc. This, in conjunction with [horizontal alignment](#horizontal-alignment) classes, is very useful for centering layouts with uneven column sizes as viewport width changes.
+
+<div class="bd-example-row">
+{% example html %}
+<div class="container">
+  <div class="row flex-items-md-center">
+    <div class="col-xs col-lg-2">
+      1 of 3
+    </div>
+    <div class="col-xs-12 col-md-auto">
+      Variable width content
+    </div>
+    <div class="col-xs col-lg-2">
+      3 of 3
+    </div>
+  </div>
+  <div class="row">
+    <div class="col-xs">
+      1 of 3
+    </div>
+    <div class="col-xs-12 col-md-auto">
+      Variable width content
+    </div>
+    <div class="col-xs col-lg-2">
+      3 of 3
+    </div>
+  </div>
+</div>
+{% endexample %}
+</div>
+
 ## Responsive flexbox
 
 Unlike the default grid system, the flexbox grid requires a class for full-width columns. If you have a `.col-sm-6` and don't add `.col-xs-12`, your `xs` grid will not render correctly. Note that flexbox grid tiers still scale up across breakpoints, so if you want two 50% wide columns across `sm`, `md`, and `lg`, you only need to set `.col-sm-6`.
diff --git a/docs/layout/overview.md b/docs/layout/overview.md
index 3e6c7e7e0..c22203fde 100644
--- 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-navbar-fixed:      1030 !default;
+$zindex-navbar-sticky:     1030 !default;
+$zindex-modal-backdrop:    1040 !default;
+$zindex-modal:             1050 !default;
+$zindex-popover:           1060 !default;
+$zindex-tooltip:           1070 !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.