Merge pull request #748 from alphagov/document-sass

Document (non-contentious parts of) Sass settings layer

app/assets/scss/app-ie8.scss

@@ -1,6 +1,2 @@
-// If you want to display the currently active breakpoint in the top
-// right corner of your site during development, add the breakpoints
-// to this list, ordered by width, e.g. (mobile, tablet, desktop).
-$mq-show-breakpoints: (desktop);
 @import "../../../src/all-ie8";
 @import "partials/app";

app/assets/scss/app.scss

@@ -1,6 +1,4 @@
-// If you want to display the currently active breakpoint in the top
-// right corner of your site during development, add the breakpoints
-// to this list, ordered by width, e.g. (mobile, tablet, desktop).
-$mq-show-breakpoints: (mobile, tablet, desktop);
+$govuk-show-breakpoints: true;
+
 @import "../../../src/all";
 @import "partials/app";

src/components/button/_button.scss

@@ -4,6 +4,11 @@
 
 @include govuk-exports("govuk/component/button") {
 
+  $govuk-button-colour: #00823b;
+  $govuk-button-hover-colour: darken($govuk-button-colour, 5%);
+  $govuk-button-shadow-colour: darken($govuk-button-colour, 15%);
+  $govuk-button-text-colour: $govuk-white;
+
   // Because the shadow (s0) is visually 'part of' the button, we need to reduce
   // the height of the button to compensate by adjusting its padding (s1) and
   // increase the bottom margin to include it (s2).

src/helpers/_media-queries.scss

@@ -1,4 +1,23 @@
-// We use sass-mq module for media queries
+// Import sass-mq as a helper for media queries
+
+// Pass our breakpoints and static breakpoint definitions through to sass-mq.
+$mq-breakpoints: if(variable-exists(govuk-breakpoints), $govuk-breakpoints, ());
+$mq-static-breakpoint: if(variable-exists(govuk-ie8-breakpoint), $govuk-ie8-breakpoint, desktop);
+
+$mq-show-breakpoints: ();
+
+@if (variable-exists(govuk-show-breakpoints) and $govuk-show-breakpoints) {
+  $mq-show-breakpoints: map-keys($govuk-breakpoints);
+}
+
+// When building a stylesheet for IE8, set $mq-responsive to false in order to
+// 'rasterize' any media queries.
+
+@if (variable-exists(govuk-is-ie8) and $govuk-is-ie8) {
+  $mq-responsive: false;
+} @else {
+  $mq-responsive: true;
+}
 
 // This is a horrible, horrible hack to prevent the 'dev mode' CSS to display
 // the current breakpoint from being included multiple times.

src/helpers/_typography.scss

@@ -3,18 +3,18 @@
 // Sets the font family and associated properties, such as font smoothing. Also
 // overrides the font for print.
 
-@mixin govuk-typography-common($font-family: $govuk-font-stack) {
+@mixin govuk-typography-common($font-family: $govuk-font-family) {
   font-family: $font-family;
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 
   // If using NTA, include the font-face definition
-  @if ($govuk-font-stack == $govuk-nta-light) {
+  @if ($govuk-font-family == $govuk-font-family-nta) {
     @include govuk-font-face-nta;
   }
 
   @include mq($media-type: print) {
-    font-family: $govuk-font-stack-print;
+    font-family: $govuk-font-family-print;
   }
 }
 
@@ -215,7 +215,7 @@
 // Regular weights, tabular numbers
 
 @mixin govuk-font-regular-tabular {
-  @include govuk-typography-common($font-family: $govuk-nta-light-tabular);
+  @include govuk-typography-common($font-family: $govuk-font-family-tabular);
   @include govuk-typography-weight-regular;
 }
 
@@ -262,7 +262,7 @@
 // Bold weights, tabular numbers
 
 @mixin govuk-font-bold-tabular {
-  @include govuk-typography-common($font-family: $govuk-nta-light-tabular);
+  @include govuk-typography-common($font-family: $govuk-font-family-tabular);
   @include govuk-typography-weight-bold;
 }
 

src/helpers/grid.test.js

@@ -14,11 +14,15 @@ const sassConfig = {
 }
 describe('grid system', () => {
   const sassImports = `
-    @import "tools/exports";
+    @import "settings/ie8";
+    @import "settings/media-queries";
     @import "settings/spacing";
     @import "settings/measurements";
+
     @import "helpers/grid";
     @import "helpers/media-queries";
+
+    @import "tools/exports";
   `
   describe('grid-width function', () => {
     it('outputs the specified key value from the map of widths', async () => {
@@ -115,7 +119,7 @@ describe('grid system', () => {
           box-sizing: border-box;
           width: 100%;
           padding: 0 15px; }
-          @media (min-width: 46.25em) {
+          @media (min-width: 40.0625em) {
             .govuk-grid-column-full {
               width: 100%;
               float: left; } }`)
@@ -137,7 +141,7 @@ describe('grid system', () => {
           box-sizing: border-box;
           width: 100%;
           padding: 0 15px; }
-          @media (min-width: 46.25em) {
+          @media (min-width: 40.0625em) {
             .govuk-grid-column-two-thirds {
               width: 66.6666%;
               float: left; } }
@@ -148,20 +152,20 @@ describe('grid system', () => {
       const sass = `
         ${sassImports}
 
-        @include govuk-grid-column(three-quarters, $class:'large-columnumn');
+        @include govuk-grid-column(three-quarters, $class:'large-column');
       `
       const results = await sassRender({ data: sass, ...sassConfig })
 
       expect(results.css
         .toString()
         .trim())
         .toBe(outdent`
-        .large-columnumn-three-quarters {
+        .large-column-three-quarters {
           box-sizing: border-box;
           width: 100%;
           padding: 0 15px; }
-          @media (min-width: 46.25em) {
-            .large-columnumn-three-quarters {
+          @media (min-width: 40.0625em) {
+            .large-column-three-quarters {
               width: 75%;
               float: left; } }
         `)
@@ -182,7 +186,7 @@ describe('grid system', () => {
         .govuk-grid-column-one-quarter {
           box-sizing: border-box;
           padding: 0 15px; }
-          @media (min-width: 61.25em) {
+          @media (min-width: 48.0625em) {
             .govuk-grid-column-one-quarter {
               width: 25%;
               float: left; } }
@@ -227,7 +231,7 @@ describe('grid system', () => {
           box-sizing: border-box;
           width: 100%;
           padding: 0 15px; }
-          @media (min-width: 46.25em) {
+          @media (min-width: 40.0625em) {
             .govuk-grid-column-one-half {
               width: 50%;
               float: right; } }

src/helpers/spacing.test.js

@@ -14,7 +14,10 @@ const sassConfig = {
 }
 
 const sassBootstrap = `
-  $mq-breakpoints: (
+  @import "settings/media-queries";
+  @import "settings/ie8";
+
+  $govuk-breakpoints: (
     my_breakpoint: 30em
   );
 

src/helpers/typography.test.js

@@ -14,7 +14,10 @@ const sassConfig = {
 }
 
 const sassBootstrap = `
-  $mq-breakpoints: (
+  @import "settings/media-queries";
+  @import "settings/ie8";
+
+  $govuk-breakpoints: (
     my_breakpoint: 30em
   );
 

src/settings/_all.scss

@@ -16,6 +16,6 @@
 @import "spacing";
 @import "measurements";
 
-@import "typography-font-stacks";
+@import "typography-font-families";
 @import "typography-font";
 @import "typography-responsive";

src/settings/_assets.scss

@@ -1,22 +1,29 @@
+////
+/// @group settings/assets
+////
+
 /// Path to the assets directory, with trailing slash.
 ///
 /// This is the directory where the images and fonts subdirectories live. You
 /// will need to make this directory available via your application – see the
 /// README for details.
 ///
 /// @type String
+/// @access public
 
 $govuk-assets-path: "/assets/" !default;
 
 /// Path to the images folder, with trailing slash.
 ///
 /// @type String
+/// @access public
 
 $govuk-images-path: "#{$govuk-assets-path}images/" !default;
 
 /// Path to the fonts folder, with trailing slash.
 ///
 /// @type String
+/// @access public
 
 $govuk-fonts-path: "#{$govuk-assets-path}fonts/" !default;
 
@@ -37,10 +44,13 @@ $govuk-fonts-path: "#{$govuk-assets-path}fonts/" !default;
 /// @example scss - Custom asset handling
 ///
 ///   @function my-url-handler($filename) {
-///     @return ''; // Some custom URL handling
+///     // Some custom URL handling
+///     @return url('example.jpg');
 ///   }
 ///
 ///   $govuk-image-url-function: 'my-url-handler';
+///
+/// @access public
 
 $govuk-image-url-function: false !default;
 
@@ -61,9 +71,12 @@ $govuk-image-url-function: false !default;
 /// @example scss - Custom asset handling
 ///
 ///   @function my-url-handler($filename) {
-///     @return ''; // Some custom URL handling
+///     // Some custom URL handling
+///     @return url('example.woff');
 ///   }
 ///
 ///   $govuk-font-url-function: 'my-url-handler';
+///
+/// @access public
 
 $govuk-font-url-function: false !default;