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

6 files changed, 106 insertions, 62 deletions

diff --git a/docs/utilities/display-property.md b/docs/utilities/display-property.md
deleted file mode 100644
index 50ea29367..000000000
--- a/docs/utilities/display-property.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-layout: docs
-title: Display property
-group: utilities
----
-
-Use `.d-block`, `.d-inline`, or `.d-inline-block` to simply set an element's [`display` property](https://developer.mozilla.org/en-US/docs/Web/CSS/display) to `block`, `inline`, or `inline-block` (respectively).
-
-To make an element `display: none`, use our [responsive utilities]({{ site.baseurl }}/layout/responsive-utilities/) instead.
-
-{% example html %}
-<div class="d-inline bg-success">Inline</div>
-<div class="d-inline bg-success">Inline</div>
-{% endexample %}
-
-{% example html %}
-<span class="d-block bg-primary">Block</span>
-{% endexample %}
-
-{% example html %}
-<div class="d-inline-block bg-warning">
-  <h3>inline-block</h3>
-  Boot that strap!
-</div>
-<div class="d-inline-block bg-warning">
-  <h3>inline-block</h3>
-  Strap that boot!
-</div>
-{% endexample %}
diff --git a/docs/utilities/display.md b/docs/utilities/display.md
new file mode 100644
index 000000000..27f70e0b2
--- /dev/null
+++ b/docs/utilities/display.md
@@ -0,0 +1,64 @@
+---
+layout: docs
+title: Display property
+group: utilities
+---
+
+Quickly and responsively toggle the `display` value of components and more with our display utilities. Includes support for some of the more common values, as well as some extras for controlling `display` when printing.
+
+## Contents
+
+* Will be replaced with the ToC, excluding the "Contents" header
+{:toc}
+
+## Common `display` values
+
+The [`display` property](https://developer.mozilla.org/en-US/docs/Web/CSS/display) accepts a handful of values and we support many of them with utility classes. We purposefully don't provide every value as a utility, so here's what we support:
+
+- `.d-none`
+- `.d-inline`
+- `.d-inline-block`
+- `.d-block`
+- `.d-table`
+- `.d-table-cell`
+- `.d-flex`
+- `.d-inline-flex`
+
+Put them to use by applying any of the classes to an element of your choice. For example, here's how you could use the inline, block, or inline-block utilities (the same applies to the other classes).
+
+{% example html %}
+<div class="d-inline bg-success">d-inline</div>
+<div class="d-inline bg-success">d-inline</div>
+{% endexample %}
+
+{% example html %}
+<span class="d-block bg-primary">d-block</span>
+{% endexample %}
+
+{% example html %}
+<div class="d-inline-block bg-warning">d-inline-block</div>
+<div class="d-inline-block bg-warning">d-inline-block</div>
+{% endexample %}
+
+Responsive variations also exist for every single utility mentioned above.
+
+{% for bp in site.data.breakpoints %}
+- `.d{{ bp.abbr }}-none`
+- `.d{{ bp.abbr }}-inline`
+- `.d{{ bp.abbr }}-inline-block`
+- `.d{{ bp.abbr }}-block`
+- `.d{{ bp.abbr }}-table`
+- `.d{{ bp.abbr }}-table-cell`
+- `.d{{ bp.abbr }}-flex`
+- `.d{{ bp.abbr }}-inline-flex`{% endfor %}
+
+## Display in print
+
+Change the `display` value of elements when printing with our print display utilities.
+
+| Class | Print style |
+| --- | --- |
+| `.d-print-block` | Applies `display: block` to the element when printing |
+| `.d-print-inline` | Applies `display: inline` to the element when printing |
+| `.d-print-inline-block` | Applies `display: inline-block` to the element when printing |
+| `.d-print-none` | Applies `display: none` to the element when printing |
diff --git a/docs/utilities/invisible-content.md b/docs/utilities/invisible-content.md
deleted file mode 100644
index 84da6ad01..000000000
--- a/docs/utilities/invisible-content.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-layout: docs
-title: Invisible content
-group: utilities
----
-
-The `.invisible` class can be used to toggle only the visibility of an element, meaning its `display` is not modified and the element can still affect the flow of the document.
-
-{% highlight html %}
-<div class="invisible">...</div>
-{% endhighlight %}
-
-{% highlight scss %}
-// Class
-.invisible {
-  visibility: hidden;
-}
-
-// Usage as a mixin
-.element {
-  @include invisible;
-}
-{% endhighlight %}
diff --git a/docs/utilities/responsive-helpers.md b/docs/utilities/responsive-helpers.md
index 35e7fcf2f..0f1a43ee1 100644
--- a/docs/utilities/responsive-helpers.md
+++ b/docs/utilities/responsive-helpers.md
@@ -14,7 +14,7 @@ Rules are directly applied to `<iframe>`, `<embed>`, `<video>`, and `<object>` e
 
 {% example html %}
 <div class="embed-responsive embed-responsive-16by9">
-  <iframe class="embed-responsive-item" src="//www.youtube.com/embed/zpOULjyy-n8?rel=0" allowfullscreen></iframe>
+  <iframe class="embed-responsive-item" src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" allowfullscreen></iframe>
 </div>
 {% endexample %}
 
diff --git a/docs/utilities/spacing.md b/docs/utilities/spacing.md
index 0a5132941..fa8a0d76c 100644
--- a/docs/utilities/spacing.md
+++ b/docs/utilities/spacing.md
@@ -35,11 +35,11 @@ Where *sides* is one of:
 Where *size* is one of:
 
 * `0` - for classes that eliminate the `margin` or `padding` by setting it to `0`
-* `1` - (by default) for classes that set the `margin` or `padding` to `$spacer-x * .25` or `$spacer-y * .25`
-* `2` - (by default) for classes that set the `margin` or `padding` to `$spacer-x * .5` or `$spacer-y * .5`
-* `3` - (by default) for classes that set the `margin` or `padding` to `$spacer-x` or `$spacer-y`
-* `4` - (by default) for classes that set the `margin` or `padding` to `$spacer-x * 1.5` or `$spacer-y * 1.5`
-* `5` - (by default) for classes that set the `margin` or `padding` to `$spacer-x * 3` or `$spacer-y * 3`
+* `1` - (by default) for classes that set the `margin` or `padding` to `$spacer * .25`
+* `2` - (by default) for classes that set the `margin` or `padding` to `$spacer * .5`
+* `3` - (by default) for classes that set the `margin` or `padding` to `$spacer`
+* `4` - (by default) for classes that set the `margin` or `padding` to `$spacer * 1.5`
+* `5` - (by default) for classes that set the `margin` or `padding` to `$spacer * 3`
 
 (You can add more sizes by adding entries to the `$spacers` Sass map variable.)
 
@@ -53,16 +53,16 @@ Here are some representative examples of these classes:
 }
 
 .ml-1 {
-  margin-left: ($spacer-x * .25) !important;
+  margin-left: ($spacer * .25) !important;
 }
 
 .px-2 {
-  padding-left: ($spacer-x * .5) !important;
-  padding-right: ($spacer-x * .5) !important;
+  padding-left: ($spacer * .5) !important;
+  padding-right: ($spacer * .5) !important;
 }
 
 .p-3 {
-  padding: $spacer-y $spacer-x !important;
+  padding: $spacer !important;
 }
 {% endhighlight %}
 
diff --git a/docs/utilities/visibility.md b/docs/utilities/visibility.md
new file mode 100644
index 000000000..5b7d28664
--- /dev/null
+++ b/docs/utilities/visibility.md
@@ -0,0 +1,32 @@
+---
+layout: docs
+title: Visibility
+group: utilities
+---
+
+Set the `visibility` of elements with our visibility utilities. These do not modify the `display` value at all and are helpful for hiding content from most users, but still keeping them for screen readers.
+
+Apply `.visible` or `.invisible` as needed.
+
+{% highlight html %}
+<div class="visible">...</div>
+<div class="invisible">...</div>
+{% endhighlight %}
+
+{% highlight scss %}
+// Class
+.visible {
+  visibility: visible;
+}
+.invisible {
+  visibility: hidden;
+}
+
+// Usage as a mixin
+.element {
+  @include invisible(visible);
+}
+.element {
+  @include invisible(hidden);
+}
+{% endhighlight %}