Refactor spacing API

CHANGELOG.md

@@ -75,6 +75,36 @@ Note: We're not following semantic versioning yet, we are going to talk about th
 
   ([PR #748](https://github.com/alphagov/govuk-frontend/pull/748))
 
+- Spacing has been refactored. You will need to update Sass that currently uses GOV.UK Frontend spacing:
+
+  - Instead of
+  ``` css
+  $govuk-spacing-scale-*
+  ```
+  use
+  ``` css
+  govuk-spacing(*)
+  ```
+  where `*` is the number on the spacing scale. The scale itself has remained the same so that `$govuk-spacing-scale-3` corresponds to `govuk-spacing(3)`. This change allows us to control the error messaging when incorrect values are used and to deprecate variables. The values of spacing variables can also be overridden by consumers.
+
+  - Instead of:
+  ``` css
+  @include govuk-responsive-margin($govuk-spacing-responsive-2, "bottom");
+  @include govuk-responsive-padding($govuk-spacing-responsive-2, "bottom");
+  ```
+  use
+  ``` css
+  @include govuk-responsive-margin(2, "bottom");
+  @include govuk-responsive-padding(2, "bottom");
+  ```
+  This change, again, allows us to control the error messaging since spacing variables are not exposed directly. Also, the spacing scale itself has not changed so that `$govuk-spacing-responsive-2` corresponds to `2` when passed to the padding and margin mixins.
+
+  This PR also updates tests and sass-docs of spacing variables and helpers.
+
+  Additionally, this PR hardcodes the value of `$govuk-gutter`, see PR for more details.
+
+  ([PR #779](https://github.com/alphagov/govuk-frontend/pull/779))
+
 - Remove `pageStart` block from template, as could result in rendering issues in older IE.
   ([PR #765](https://github.com/alphagov/govuk-frontend/pull/765))
 

src/components/back-link/_back-link.scss

@@ -12,8 +12,8 @@
     display: inline-block;
     position: relative;
 
-    margin-top: $govuk-spacing-scale-3;
-    margin-bottom: $govuk-spacing-scale-3;
+    margin-top: govuk-spacing(3);
+    margin-bottom: govuk-spacing(3);
 
     // Allow space for the arrow
     padding-left: 14px;

src/components/breadcrumbs/_breadcrumbs.scss

@@ -23,8 +23,8 @@
     @include govuk-font($size: 16);
     @include govuk-text-colour;
 
-    margin-top: $govuk-spacing-scale-3;
-    margin-bottom: $govuk-spacing-scale-2;
+    margin-top: govuk-spacing(3);
+    margin-bottom: govuk-spacing(2);
   }
 
   .govuk-breadcrumbs__list {
@@ -40,12 +40,12 @@
     display: inline-block;
     position: relative;
 
-    margin-bottom: $govuk-spacing-scale-1;
+    margin-bottom: govuk-spacing(1);
 
     // Add both margin and padding such that the chevron appears centrally
     // between each breadcrumb item
-    margin-left: $govuk-spacing-scale-2;
-    padding-left: $govuk-spacing-scale-2 + $chevron-altitude-calculated;
+    margin-left: govuk-spacing(2);
+    padding-left: govuk-spacing(2) + $chevron-altitude-calculated;
 
     float: left;
 

src/components/button/_button.scss

@@ -23,8 +23,8 @@
     position: relative;
     width: 100%;
     margin-top: 0;
-    @include govuk-responsive-margin($govuk-spacing-responsive-6, "bottom", $adjustment: $button-shadow-size); // s2
-    padding: ($govuk-spacing-scale-2 - $govuk-border-width-form-element - ($button-shadow-size / 2)) $govuk-spacing-scale-2; // s1
+    @include govuk-responsive-margin(6, "bottom", $adjustment: $button-shadow-size); // s2
+    padding: (govuk-spacing(2) - $govuk-border-width-form-element - ($button-shadow-size / 2)) govuk-spacing(2); // s1
     border: $govuk-border-width-form-element solid transparent;
     border-radius: 0;
     color: $govuk-button-text-colour;
@@ -146,10 +146,10 @@
     @include govuk-typography-responsive($size: 24, $override-line-height: 1);
 
     min-height: auto;
-    padding-top: $govuk-spacing-scale-2 - $govuk-border-width-form-element;
-    padding-right: $govuk-spacing-scale-7;
-    padding-bottom: $govuk-spacing-scale-2 - $govuk-border-width-form-element;
-    padding-left: $govuk-spacing-scale-3;
+    padding-top: govuk-spacing(2) - $govuk-border-width-form-element;
+    padding-right: govuk-spacing(7);
+    padding-bottom: govuk-spacing(2) - $govuk-border-width-form-element;
+    padding-left: govuk-spacing(3);
 
     background-image: govuk-image-url("icon-pointer.png");
     background-repeat: no-repeat;
@@ -168,13 +168,13 @@
   $offset: 2;
 
   .govuk-button {
-    padding-top: ($govuk-spacing-scale-2 - $govuk-border-width-form-element - ($button-shadow-size / 2) + $offset); // s1
-    padding-bottom: ($govuk-spacing-scale-2 - $govuk-border-width-form-element - ($button-shadow-size / 2) - $offset + 1); // s1
+    padding-top: (govuk-spacing(2) - $govuk-border-width-form-element - ($button-shadow-size / 2) + $offset); // s1
+    padding-bottom: (govuk-spacing(2) - $govuk-border-width-form-element - ($button-shadow-size / 2) - $offset + 1); // s1
   }
 
   .govuk-button--start {
-    padding-top: ($govuk-spacing-scale-2 - $govuk-border-width-form-element - ($button-shadow-size / 2) + $offset); // s1
-    padding-bottom: ($govuk-spacing-scale-2 - $govuk-border-width-form-element - ($button-shadow-size / 2) - $offset + 1); // s1
+    padding-top: (govuk-spacing(2) - $govuk-border-width-form-element - ($button-shadow-size / 2) + $offset); // s1
+    padding-bottom: (govuk-spacing(2) - $govuk-border-width-form-element - ($button-shadow-size / 2) - $offset + 1); // s1
   }
 
 }

src/components/checkboxes/_checkboxes.scss

@@ -8,8 +8,8 @@
 @import "../label/label";
 
 @include govuk-exports("govuk/component/checkboxes") {
-  $govuk-checkboxes-size: $govuk-spacing-scale-7;
-  $govuk-checkboxes-label-padding-left-right: $govuk-spacing-scale-3;
+  $govuk-checkboxes-size: govuk-spacing(7);
+  $govuk-checkboxes-label-padding-left-right: govuk-spacing(3);
 
   .govuk-checkboxes__item {
     @include govuk-font($size: 19);
@@ -19,7 +19,7 @@
 
     min-height: $govuk-checkboxes-size;
 
-    margin-bottom: $govuk-spacing-scale-2;
+    margin-bottom: govuk-spacing(2);
     padding: 0 0 0 $govuk-checkboxes-size;
 
     clear: left;
@@ -58,7 +58,7 @@
 
   .govuk-checkboxes__label {
     display: block;
-    padding: 8px $govuk-checkboxes-label-padding-left-right $govuk-spacing-scale-1;
+    padding: 8px $govuk-checkboxes-label-padding-left-right govuk-spacing(1);
     cursor: pointer;
     // remove 300ms pause on mobile
     -ms-touch-action: manipulation;
@@ -129,7 +129,7 @@
   $conditional-padding-left: $conditional-border-padding + $govuk-checkboxes-label-padding-left-right;
 
   .govuk-checkboxes__conditional {
-    @include govuk-responsive-margin($govuk-spacing-responsive-4, "bottom");
+    @include govuk-responsive-margin(4, "bottom");
     margin-left: $conditional-margin-left;
     padding-left: $conditional-padding-left;
     border-left: $conditional-border-width solid $govuk-border-colour;

src/components/date-input/_date-input.scss

@@ -14,7 +14,7 @@
 
   .govuk-date-input__item {
     width: 50px;
-    margin-right: $govuk-spacing-scale-4;
+    margin-right: govuk-spacing(4);
     margin-bottom: 0;
     float: left;
     clear: none;

src/components/details/_details.scss

@@ -7,7 +7,7 @@
   .govuk-details {
     @include govuk-font($size: 19);
     @include govuk-text-colour;
-    @include govuk-responsive-margin($govuk-spacing-responsive-6, "bottom");
+    @include govuk-responsive-margin(6, "bottom");
 
     display: block;
   }
@@ -19,10 +19,10 @@
     // Absolutely position the marker against this element
     position: relative;
 
-    margin-bottom: $govuk-spacing-scale-1;
+    margin-bottom: govuk-spacing(1);
 
     // Allow for absolutely positioned marker and align with disclosed text
-    padding-left: $govuk-spacing-scale-4 + $govuk-border-width;
+    padding-left: govuk-spacing(4) + $govuk-border-width;
 
     // Style the summary to look like a link...
     color: $govuk-link-colour;
@@ -70,14 +70,14 @@
   }
 
   .govuk-details__text {
-    padding: $govuk-spacing-scale-3;
-    padding-left: $govuk-spacing-scale-4;
+    padding: govuk-spacing(3);
+    padding-left: govuk-spacing(4);
     border-left: $govuk-border-width solid $govuk-border-colour;
   }
 
   .govuk-details__text p {
     margin-top: 0;
-    margin-bottom: $govuk-spacing-scale-4;
+    margin-bottom: govuk-spacing(4);
   }
 
   .govuk-details__text p:last-child {

src/components/error-message/_error-message.scss

@@ -7,7 +7,7 @@
     @include govuk-font($size: 19, $weight: bold);
 
     display: block;
-    margin-bottom: $govuk-spacing-scale-3;
+    margin-bottom: govuk-spacing(3);
     clear: both;
 
     color: $govuk-error-colour;

src/components/error-summary/_error-summary.scss

@@ -8,8 +8,8 @@
 
   .govuk-error-summary {
     @include govuk-text-colour;
-    @include govuk-responsive-padding($govuk-spacing-responsive-4);
-    @include govuk-responsive-margin($govuk-spacing-responsive-8, "bottom");
+    @include govuk-responsive-padding(4);
+    @include govuk-responsive-margin(8, "bottom");
     @include govuk-focusable;
 
     border: $govuk-border-width-mobile solid $govuk-error-colour;
@@ -23,15 +23,15 @@
     @include govuk-font($size: 24, $weight: bold);
 
     margin-top: 0;
-    @include govuk-responsive-margin($govuk-spacing-responsive-4, "bottom");
+    @include govuk-responsive-margin(4, "bottom");
   }
 
   .govuk-error-summary__body {
     @include govuk-font($size: 19);
 
     p {
       margin-top: 0;
-      @include govuk-responsive-margin($govuk-spacing-responsive-4, "bottom");
+      @include govuk-responsive-margin(4, "bottom");
     }
   }
 

src/components/fieldset/_fieldset.scss

@@ -20,7 +20,7 @@
     box-sizing: border-box; // 1
     display: table;         // 2
     max-width: 100%;        // 1
-    margin-bottom: $govuk-spacing-scale-3;
+    margin-bottom: govuk-spacing(3);
     padding: 0;
     // Hack to let legends or elements within legends have margins in webkit browsers
     overflow: hidden;

src/components/footer/_footer.scss

@@ -22,8 +22,8 @@
 
   .govuk-footer {
     @include govuk-font($size: 16);
-    @include govuk-responsive-padding($govuk-spacing-responsive-7, "top");
-    @include govuk-responsive-padding($govuk-spacing-responsive-5, "bottom");
+    @include govuk-responsive-padding(7, "top");
+    @include govuk-responsive-padding(5, "bottom");
 
     border-top: 1px solid $govuk-footer-border-top;
     color: $govuk-footer-text;
@@ -60,7 +60,7 @@
 
   .govuk-footer__section-break {
     margin: 0; // Reset `<hr>` default margins
-    @include govuk-responsive-margin($govuk-spacing-responsive-8, "bottom");
+    @include govuk-responsive-margin(8, "bottom");
     border: 0; // Reset `<hr>` default borders
     border-bottom: 1px solid $govuk-footer-border;
   }
@@ -76,7 +76,7 @@
 
   .govuk-footer__meta-item {
     margin-right: $govuk-gutter-half;
-    margin-bottom: $govuk-spacing-scale-5;
+    margin-bottom: govuk-spacing(5);
     margin-left: $govuk-gutter-half;
   }
 
@@ -89,9 +89,9 @@
 
   .govuk-footer__licence-logo {
     display: inline-block;
-    margin-right: $govuk-spacing-scale-2;
+    margin-right: govuk-spacing(2);
     @include mq ($until: desktop) {
-      margin-bottom: $govuk-spacing-scale-3;
+      margin-bottom: govuk-spacing(3);
     }
     vertical-align: top;
   }
@@ -103,7 +103,7 @@
   .govuk-footer__copyright-logo {
     display: inline-block;
     min-width: $govuk-footer-crest-image-width;
-    padding-top: ($govuk-footer-crest-image-height + $govuk-spacing-scale-2);
+    padding-top: ($govuk-footer-crest-image-height + govuk-spacing(2));
     background-image: govuk-image-url("govuk-crest.png");
     @include govuk-device-pixel-ratio {
       background-image: govuk-image-url("govuk-crest-2x.png");
@@ -118,21 +118,21 @@
 
   .govuk-footer__inline-list {
     margin-top: 0;
-    margin-bottom: $govuk-spacing-scale-3;
+    margin-bottom: govuk-spacing(3);
     padding: 0;
   }
 
   .govuk-footer__inline-list-item {
     display: inline-block;
-    margin-right: $govuk-spacing-scale-3;
-    margin-bottom: $govuk-spacing-scale-1;
+    margin-right: govuk-spacing(3);
+    margin-bottom: govuk-spacing(1);
   }
 
   .govuk-footer__heading {
-    @include govuk-responsive-margin($govuk-spacing-responsive-7, "bottom");
-    padding-bottom: $govuk-spacing-scale-4;
+    @include govuk-responsive-margin(7, "bottom");
+    padding-bottom: govuk-spacing(4);
     @include mq ($until: tablet) {
-      padding-bottom: $govuk-spacing-scale-2;
+      padding-bottom: govuk-spacing(2);
     }
     border-bottom: 1px solid $govuk-footer-border;
   }
@@ -185,7 +185,7 @@
   }
 
   .govuk-footer__list-item {
-    @include govuk-responsive-margin($govuk-spacing-responsive-4, "bottom");
+    @include govuk-responsive-margin(4, "bottom");
   }
 
   .govuk-footer__list-item:last-child {