5 files changed, 46 insertions, 19 deletions
diff --git a/docs/assets/scss/_component-examples.scss b/docs/assets/scss/_component-examples.scss
index 1ab49218c..a429b9aae 100644
--- a/docs/assets/scss/_component-examples.scss
+++ b/docs/assets/scss/_component-examples.scss
@@ -324,7 +324,7 @@
 
 .highlight {
   padding: 1rem;
-  margin: 1rem (-$grid-gutter-width / 2);
+  margin: 1rem (-$grid-gutter-width-base / 2);
   background-color: #f7f7f9;
 
   @include media-breakpoint-up(sm) {
diff --git a/docs/assets/scss/_featurettes.scss b/docs/assets/scss/_featurettes.scss
index a74834387..03119ce50 100644
--- a/docs/assets/scss/_featurettes.scss
+++ b/docs/assets/scss/_featurettes.scss
@@ -26,10 +26,10 @@
 
   @include media-breakpoint-up(md) {
     .col-sm-6:first-child {
-      padding-right: ($grid-gutter-width * 1.5);
+      padding-right: ($grid-gutter-width-base * 1.5);
     };
     .col-sm-6:last-child {
-      padding-left: ($grid-gutter-width * 1.5);
+      padding-left: ($grid-gutter-width-base * 1.5);
     }
   }
 }
diff --git a/docs/assets/scss/_masthead.scss b/docs/assets/scss/_masthead.scss
index f0ebe9363..aa59ffbfc 100644
--- a/docs/assets/scss/_masthead.scss
+++ b/docs/assets/scss/_masthead.scss
@@ -2,7 +2,7 @@
 
 .bd-masthead {
   position: relative;
-  padding: 3rem ($grid-gutter-width / 2) 2rem;
+  padding: 3rem ($grid-gutter-width-base / 2) 2rem;
   color: $bd-purple-light;
   text-align: center;
   background-image: linear-gradient(135deg, darken($bd-purple, 20%), $bd-purple, lighten(saturate($bd-purple, 5%), 15%));
diff --git a/docs/assets/scss/_page-header.scss b/docs/assets/scss/_page-header.scss
index 457d3fbef..e51459903 100644
--- a/docs/assets/scss/_page-header.scss
+++ b/docs/assets/scss/_page-header.scss
@@ -1,7 +1,7 @@
 // scss-lint:disable ImportantRule
 
 .bd-pageheader {
-  padding: 2rem ($grid-gutter-width / 2);
+  padding: 2rem ($grid-gutter-width-base / 2);
   margin-bottom: 1.5rem;
   color: $bd-purple-light;
   text-align: center;
diff --git a/docs/layout/grid.md b/docs/layout/grid.md
index ec80156a4..47e8f4470 100644
--- a/docs/layout/grid.md
+++ b/docs/layout/grid.md
@@ -1,4 +1,4 @@
----
+atom---
 layout: docs
 title: Grid system
 description: Documentation and examples for using Bootstrap's powerful, responsive, and mobile-first grid system.
@@ -34,14 +34,14 @@ Sounds good? Great, let's move on to seeing all that in an example.
 If you're using Bootstrap's compiled CSS, this the example you'll want to start with.
 
 {% example html %}
-<div class="container">
+<div class="container">a
   <div class="row">
     <div class="col-sm-4">
-      One of three columns
+      One of three columnsa
     </div>
     <div class="col-sm-4">
       One of three columns
-    </div>
+    </div>atom
     <div class="col-sm-4">
       One of three columns
     </div>
@@ -140,7 +140,15 @@ Variables and maps determine the number of columns, the gutter width, and the me
 
 {% highlight scss %}
 $grid-columns:      12;
-$grid-gutter-width: 30px;
+$grid-gutter-width-base: 30px;
+
+$grid-gutter-widths: (
+  xs: $grid-gutter-width-base, // 30px
+  sm: $grid-gutter-width-base, // 30px
+  md: $grid-gutter-width-base, // 30px
+  lg: $grid-gutter-width-base, // 30px
+  xl: $grid-gutter-width-base  // 30px
+)
 
 $grid-breakpoints: (
   // Extra small screen / phone
@@ -169,23 +177,27 @@ Mixins are used in conjunction with the grid variables to generate semantic CSS
 
 {% highlight scss %}
 // Creates a wrapper for a series of columns
-@mixin make-row($gutter: $grid-gutter-width) {
+@mixin make-row($gutters: $grid-gutter-widths) {
   @if $enable-flex {
     display: flex;
     flex-wrap: wrap;
   } @else {
     @include clearfix();
   }
-  margin-left:  ($gutter / -2);
-  margin-right: ($gutter / -2);
+
+  @each $breakpoint in map-keys($gutters) {
+    @include media-breakpoint-up($breakpoint) {
+      $gutter: map-get($gutters, $breakpoint);
+      margin-right: ($gutter / -2);
+      margin-left:  ($gutter / -2);
+    }
+  }
 }
 
 // Make the element grid-ready (applying everything but the width)
-@mixin make-col-ready($gutter: $grid-gutter-width) {
+@mixin make-col-ready($gutters: $grid-gutter-widths) {
   position: relative;
   min-height: 1px; // Prevent collapsing
-  padding-right: ($gutter / 2);
-  padding-left:  ($gutter / 2);
 
   // Prevent columns from becoming too narrow when at smaller grid tiers by
   // always setting `width: 100%;`. This works because we use `flex` values
@@ -193,6 +205,14 @@ Mixins are used in conjunction with the grid variables to generate semantic CSS
   @if $enable-flex {
     width: 100%;
   }
+
+  @each $breakpoint in map-keys($gutters) {
+    @include media-breakpoint-up($breakpoint) {
+      $gutter: map-get($gutters, $breakpoint);
+      padding-right: ($gutter / 2);
+      padding-left:  ($gutter / 2);
+    }
+  }
 }
 
 @mixin make-col($size, $columns: $grid-columns) {
@@ -464,11 +484,18 @@ Using our built-in grid Sass variables and maps, it's possible to completely cus
 
 ### Columns and gutters
 
-The number of grid columns and their horizontal padding (aka, gutters) can be modified via Sass variables. `$grid-columns` is used to generate the widths (in percent) of each individual column while `$grid-gutter-width` is divided evenly across `padding-left` and `padding-right` for the column gutters.
+The number of grid columns and their horizontal padding (aka, gutters) can be modified via Sass variables. `$grid-columns` is used to generate the widths (in percent) of each individual column while `$grid-gutter-widths` allows breakpoint-specific widths that are divided evenly across `padding-left` and `padding-right` for the column gutters.
 
 {% highlight scss %}
-$grid-columns: 12;
-$grid-gutter-width: 30px;
+$grid-columns:               12 !default;
+$grid-gutter-width-base:     30px !default;
+$grid-gutter-widths: (
+  xs: $grid-gutter-width-base,
+  sm: $grid-gutter-width-base,
+  md: $grid-gutter-width-base,
+  lg: $grid-gutter-width-base,
+  xl: $grid-gutter-width-base
+) !default;
 {% endhighlight %}
 
 ### Grid tiers