add example and document bug behavior to fix #21967

diff --git a/docs/layout/grid.md b/docs/layout/grid.md
index ca3537e843f35c1f5249525a27f37cbc3799031f..2eb704550fe0a8aeb1f53f00e620d3c55ec19fb6 100644 (file)
--- a/docs/layout/grid.md
+++ b/docs/layout/grid.md
@@ -162,6 +162,22 @@ For example, here are two grid layouts that apply to every device and viewport,
 {% endexample %}
 </div>
 
+Equal-width columns can be broken into multiple lines, but there is a [Safari flexbox bug](https://github.com/philipwalton/flexbugs#11-min-and-max-size-declarations-are-ignored-when-wrapping-flex-items) that prevents this from working without an explicit `flex-basis` or `border`. Our example works thanks to the `border` being set; you can do the same with `.col { border: 1px solid transparent; }`. Alternatively, you can set the flex-basis to the width of the column (e.g., `.col { flex: 1 0 50%; }`).
+
+<div class="bd-example-row">
+{% example html %}
+<div class="container">
+  <div class="row">
+    <div class="col">Column</div>
+    <div class="col">Column</div>
+    <div class="w-100"></div>
+    <div class="col">Column</div>
+    <div class="col">Column</div>
+  </div>
+</div>
+{% endexample %}
+</div>
+
 ### Setting one column width
 
 Auto-layout for flexbox grid columns also means you can set the width of one column and have the sibling columns 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.