update responsive utility docs post-overhaul

docs/assets/scss/docs.scss

@@ -1244,10 +1244,7 @@ body {
 .visible-on,
 .hidden-on {
   .col-xs-6 {
-    .hidden-xs,
-    .hidden-sm,
-    .hidden-md,
-    .hidden-lg {
+    > .not-visible {
       color: #999;
       border: 1px solid #ddd;
     }
@@ -1256,10 +1253,7 @@ body {
 .visible-on,
 .hidden-on {
   .col-xs-6 {
-    .visible-xs-block,
-    .visible-sm-block,
-    .visible-md-block,
-    .visible-lg-block {
+    .visible {
       color: #468847;
       background-color: #dff0d8;
       border: 1px solid #d6e9c6;
@@ -1267,6 +1261,32 @@ body {
   }
 }
 
+@include media-breakpoint-only(xs) {
+  .hidden-xs-only {
+    display: none !important;
+  }
+}
+@include media-breakpoint-only(sm) {
+  .hidden-sm-only {
+    display: none !important;
+  }
+}
+@include media-breakpoint-only(md) {
+  .hidden-md-only {
+    display: none !important;
+  }
+}
+@include media-breakpoint-only(lg) {
+  .hidden-lg-only {
+    display: none !important;
+  }
+}
+@include media-breakpoint-only(xl) {
+  .hidden-xl-only {
+    display: none !important;
+  }
+}
+
 //
 // Brand guidelines
 //

docs/layout/media-queries.md

@@ -7,48 +7,64 @@ Since Bootstrap is designed to be mobile-first, we employ media queries in our C
 
 ### Common queries
 
-Bootstrap uses the following media query ranges in our source Sass files for key breakpoints in our layout, grid system, and components.
+Bootstrap mainly uses the following media query ranges in our source Sass files for key breakpoints in our layout, grid system, and components.
 
 {% highlight scss %}
-/* Extra small devices (phones, less than 768px) */
+/* Extra small devices (portrait phones, less than ???px) */
 /* No media query since this is the default in Bootstrap */
 
-/* Small devices (tablets, 768px and up) */
-@media (min-width: @screen-sm-min) { ... }
+/* Small devices (landscape phones, 34em and up) */
+@media (min-width: 34em) { ... }
 
-/* Medium devices (desktops, 992px and up) */
-@media (min-width: @screen-md-min) { ... }
+/* Medium devices (tablets, 48em and up) */
+@media (min-width: 48em) { ... }
 
-/* Large devices (large desktops, 1200px and up) */
-@media (min-width: @screen-lg-min) { ... }
-{% endhighlight %}
+/* Large devices (desktops, 62em and up) */
+@media (min-width: 62em) { ... }
 
-We occasionally expand on these media queries to include a <code>max-width</code> to limit CSS to a narrower set of devices.
+/* Extra large devices (large desktops, 75em and up) */
+@media (min-width: 75em) { ... }
+{% endhighlight %}
 
+These media queries are available via Sass mixins:
 {% highlight scss %}
-@media (max-width: @screen-xs-max) { ... }
-@media (min-width: @screen-sm-min) and (max-width: @screen-sm-max) { ... }
-@media (min-width: @screen-md-min) and (max-width: @screen-md-max) { ... }
-@media (min-width: @screen-lg-min) { ... }
+@include media-breakpoint-up(xs) { ... }
+@include media-breakpoint-up(sm) { ... }
+@include media-breakpoint-up(md) { ... }
+@include media-breakpoint-up(lg) { ... }
+@include media-breakpoint-up(lxl) { ... }
+
+// Example usage:
+@include media-breakpoint-up(sm) {
+  .some-class {
+    display: block;
+  }
+}
 {% endhighlight %}
 
-### Sass mixins
+We occasionally use media queries that go in the other direction (the given screen size *or smaller*):
+{% highlight scss %}
+/* Extra small devices (portrait phones, less than 34em) */
+@media (max-width: 33.9em) { ... }
+
+/* Small devices (landscape phones, less than 48em) */
+@media (max-width: 47.9em) { ... }
+
+/* Medium devices (tablets, less than 62em) */
+@media (max-width: 61.9em) { ... }
 
-The above media queries are also available via Sass mixins:
+/* Large devices (desktops, less than 75em) */
+@media (max-width: 74.9em) { ... }
+
+/* Extra large devices (large desktops) */
+/* No media query since the extra-large breakpoint has no upper bound on its width */
+{% endhighlight %}
 
+These media queries are available via Sass mixins:
 {% highlight scss %}
-// List of mixins
-@include media-xs { ... }
-@include media-sm { ... }
-@include media-sm-max { ... }
-@include media-md { ... }
-@include media-md-max { ... }
-@include media-lg { ... }
-
-// Usage
-@include media-xs {
-  .element {
-    display: block;
-  }
-}
+@include media-breakpoint-down(xs) { ... }
+@include media-breakpoint-down(sm) { ... }
+@include media-breakpoint-down(md) { ... }
+@include media-breakpoint-down(lg) { ... }
+@include media-breakpoint-down(lxl) { ... }
 {% endhighlight %}

docs/migration.md

@@ -67,7 +67,7 @@ The following deprecated Less/SCSS variables have been removed in v4.0.0:
 * `@screen-xs`, `@screen-xs-min`. The extra small breakpoint has no lower bound, so these variables were logically absurd. Reformulate your expression in terms of `$screen-xs-max` instead.
 * `@grid-float-breakpoint`
 
-The responsive utility classes have been overhauled. The old classes (`.hidden-xs` `.hidden-sm` `.hidden-md` `.hidden-lg` `.visible-xs-block` `.visible-xs-inline` `.visible-xs-inline-block` `.visible-sm-block` `.visible-sm-inline` `.visible-sm-inline-block` `.visible-md-block` `.visible-md-inline` `.visible-md-inline-block` `.visible-lg-block` `.visible-lg-inline` `.visible-lg-inline-block`) are gone. They have been replaced by `.hidden-xs-up` `.hidden-xs-down` `.hidden-sm-up` `.hidden-sm-down` `.hidden-md-up` `.hidden-md-down` `.hidden-lg-up` `.hidden-lg-down`. The `.hidden-*-up` classes hide the element when the viewport is at the given breakpoint or wider (e.g. `.hidden-md-up` hides an element on medium, large, and extra-large devices). The `.hidden-*-down` classes hide the element when the viewport is at the given breakpoint or smaller (e.g. `.hidden-md-down` hides an element on extra-small, small, and medium devices). Rather than using explicit `.visible-*` classes, you make an element visible by simply not hiding it at that screen size. You can combine one `.hidden-*-up` class with one `.hidden-*-down` class to show an element only on a given interval of screen sizes (e.g. `.hidden-sm-down.hidden-xl-up` shows the element only on medium and large devices). Note that the changes to the grid breakpoints in v4 means that you'll need to go one breakpoint larger to achieve the same results (e.g. `.hidden-md` is more similar to `.hidden-lg-down` than to `.hidden-md-down`). .The new responsive utility classes don't attempt to accommodate less common cases where an element's visibility can't be expressed as a single contiguous range of viewport sizes; you will instead need to custom CSS in such cases.
+The responsive utility classes have been overhauled. The old classes (`.hidden-xs` `.hidden-sm` `.hidden-md` `.hidden-lg` `.visible-xs-block` `.visible-xs-inline` `.visible-xs-inline-block` `.visible-sm-block` `.visible-sm-inline` `.visible-sm-inline-block` `.visible-md-block` `.visible-md-inline` `.visible-md-inline-block` `.visible-lg-block` `.visible-lg-inline` `.visible-lg-inline-block`) are gone. They have been replaced by `.hidden-xs-up` `.hidden-xs-down` `.hidden-sm-up` `.hidden-sm-down` `.hidden-md-up` `.hidden-md-down` `.hidden-lg-up` `.hidden-lg-down`. The `.hidden-*-up` classes hide the element when the viewport is at the given breakpoint or wider (e.g. `.hidden-md-up` hides an element on medium, large, and extra-large devices). The `.hidden-*-down` classes hide the element when the viewport is at the given breakpoint or smaller (e.g. `.hidden-md-down` hides an element on extra-small, small, and medium devices). Rather than using explicit `.visible-*` classes, you make an element visible by simply not hiding it at that screen size. You can combine one `.hidden-*-up` class with one `.hidden-*-down` class to show an element only on a given interval of screen sizes (e.g. `.hidden-sm-down.hidden-xl-up` shows the element only on medium and large devices). Note that the changes to the grid breakpoints in v4 means that you'll need to go one breakpoint larger to achieve the same results (e.g. `.hidden-md` is more similar to `.hidden-lg-down` than to `.hidden-md-down`). .The new responsive utility classes don't attempt to accommodate less common cases where an element's visibility can't be expressed as a single contiguous range of viewport sizes; you will instead need to use custom CSS in such cases.
 
 ## Misc notes to prioritize