Improvements to Sass documentation

src/helpers/_focused.scss

@@ -14,7 +14,8 @@
   // backgrounds and box-shadows disappear, so we need to ensure there's a
   // transparent outline which will be set to a visible colour.
 
-  // Since Internet Explorer 8 does not support box-shadow, we want to force the user-agent outlines
+  // Since Internet Explorer 8 does not support box-shadow, we want to force the
+  // user-agent outlines
   @include govuk-not-ie8 {
     outline: $govuk-focus-width solid transparent;
   }

src/helpers/_typography.scss

@@ -17,8 +17,12 @@
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 
-  // If the user is using the default GOV.UK Transport font we need to include the font-face declarations.
-  // We do not need to include the GOV.UK Transport font-face declarations if alphagov/govuk_template is being used since nta will already be included by default
+  // If the user is using the default GOV.UK Transport font we need to include
+  // the font-face declarations.
+  //
+  // We do not need to include the GOV.UK Transport font-face declarations if
+  // alphagov/govuk_template is being used since nta will already be included by
+  // default.
   @if ($govuk-include-default-font-face) {
     @include _govuk-font-face-govuk-transport;
   }

src/helpers/_visually-hidden.scss

@@ -18,7 +18,8 @@
 
   width: 1px iff($important, !important);
   height: 1px iff($important, !important);
-  // If margin is set to a negative value it can cause text to be announced in the wrong order in VoiceOver for OSX
+  // If margin is set to a negative value it can cause text to be announced in
+  // the wrong order in VoiceOver for OSX
   margin: 0 iff($important, !important);
   padding: 0 iff($important, !important);
 
@@ -50,7 +51,8 @@
 
   width: 1px iff($important, !important);
   height: 1px iff($important, !important);
-  // If margin is set to a negative value it can cause text to be announced in the wrong order in VoiceOver for OSX
+  // If margin is set to a negative value it can cause text to be announced in
+  // the wrong order in VoiceOver for OSX
   margin: 0 iff($important, !important);
 
   overflow: hidden iff($important, !important);

src/objects/_main-wrapper.scss

@@ -20,7 +20,8 @@
 // </div>
 
 
-/// @deprecated Replace this mixin with more direct references to the [spacing mixins](https://design-system.service.gov.uk/styles/spacing/#spacing-on-custom-components).
+/// @deprecated Replace this mixin with more direct references to the [spacing
+/// mixins](https://design-system.service.gov.uk/styles/spacing/#spacing-on-custom-components).
 @mixin govuk-main-wrapper {
   // In IE11 the `main` element can be used, but is not recognized  –
   // meaning it's not defined in IE's default style sheet,
@@ -38,9 +39,11 @@
   }
 }
 
-/// Use govuk-main-wrapper--l when you page does not have Breadcrumbs, phase banners or back links.
+/// Use govuk-main-wrapper--l when you page does not have Breadcrumbs, phase
+/// banners or back links.
 ///
-/// @deprecated Replace this mixin with more direct references to the [spacing mixins](https://design-system.service.gov.uk/styles/spacing/#spacing-on-custom-components).
+/// @deprecated Replace this mixin with more direct references to the [spacing
+/// mixins](https://design-system.service.gov.uk/styles/spacing/#spacing-on-custom-components).
 @mixin govuk-main-wrapper--l {
   @include govuk-responsive-padding(8, "top");
 }
@@ -50,9 +53,10 @@
     @include govuk-main-wrapper;
   }
 
-  // For most instances of main wrapper, :first-child will give the correct spacing without
-  // the need for the `l` modifier, but it is available in instances where there may be
-  // empty elements that would be difficult to remove.
+  // For most instances of main wrapper, :first-child will give the correct
+  // spacing without the need for the `l` modifier, but it is available in
+  // instances where there may be empty elements that would be difficult to
+  // remove.
   .govuk-main-wrapper:first-child,
   .govuk-main-wrapper--l {
     @include govuk-main-wrapper--l;

src/settings/_colours-applied.scss

@@ -26,7 +26,8 @@ $govuk-text-colour: govuk-colour("black") !default;
 
 /// Canvas background colour
 ///
-/// Used by the footer component and template to give the illusion of a long footer.
+/// Used by the footer component and template to give the illusion of a long
+/// footer.
 ///
 /// @type Colour
 /// @access public

src/settings/_compatibility.scss

@@ -1,17 +1,26 @@
 ////
-/// Compatibility with legacy repos (govuk_elements, govuk_frontend_tookkit and
-/// govuk_template) settings
+/// 'Compatibility Mode'
 ///
-/// We default these settings to `true` so that if they are missed we opt for a
-/// mild performance hit over a potential broken experience for the end-user.
+/// Enabling these flags improves compatibility if you are using GOV.UK Frontend
+/// in an application that also uses govuk_elements, govuk_frontend_toolkit or
+/// govuk_template (the 'legacy repos').
+///
+/// Enabling any of these settings will, by default:
+///
+/// - switch GOV.UK Frontend to using the same colour palette as the legacy
+///   repos, by setting `$govuk-use-legacy-palette` to true.
+///
+/// - prevent GOV.UK Frontend from using rem for font sizing, by setting
+///   `$govuk-typography-use-rem` to false.
 ///
 /// @group settings/compatibility
 ////
 
 
 /// Compatibility Mode: alphagov/govuk_frontend_toolkit
 ///
-/// True if used in a project that also includes alphagov/govuk_frontend_toolkit.
+/// Set this to true if you are also including alphagov/govuk_frontend_toolkit
+/// in your application.
 ///
 /// @type Boolean
 /// @access public
@@ -20,7 +29,16 @@ $govuk-compatibility-govukfrontendtoolkit: false !default;
 
 /// Compatibility Mode: alphagov/govuk_template
 ///
-/// True if used in a project that also includes alphagov/govuk_template.
+/// Enabling this will:
+///
+/// - prevent GOV.UK Frontend from including the New Transport typeface, as
+///   it'll use the version of New Transport included with GOV.UK Template.
+///
+/// - alter some of the CSS outputted by GOV.UK Frontend to 'counter'
+///   specific CSS rules in GOV.UK Template.
+///
+/// Set this to true if you are also including alphagov/govuk_template in your
+/// application.
 ///
 /// @type Boolean
 /// @access public
@@ -29,7 +47,13 @@ $govuk-compatibility-govuktemplate: false !default;
 
 /// Compatibility Mode: alphagov/govuk_elements
 ///
-/// True if used in a project that also includes alphagov/govuk_elements.
+/// Enabling this will:
+///
+/// - alter some of the CSS outputted by GOV.UK Frontend to 'counter'
+///   specific CSS rules in GOV.UK Elements.
+///
+/// Set this to true if you are also including alphagov/govuk_elements in your
+/// application.
 ///
 /// @type Boolean
 /// @access public

src/settings/_typography-font-families.scss

@@ -2,8 +2,8 @@
 /// @group settings/typography
 ////
 
-/// List of font families to use if using GOV.UK Transport (the default font 'stack' for
-/// GOV.UK)
+/// List of font families to use if using GOV.UK Transport (the default font
+/// 'stack' for GOV.UK)
 ///
 /// @type List
 /// @access public
@@ -15,7 +15,7 @@ $govuk-font-family-govuk-transport: "GOVUKTransport", Arial, sans-serif;
 ///
 /// @type List
 /// @access public
-/// @deprecated Will be removed once support for GOV.UK Template/Elements is dropped
+/// @deprecated To be removed once support for compatibility mode is dropped
 
 $govuk-font-family-nta: "nta", Arial, sans-serif;
 
@@ -27,6 +27,6 @@ $govuk-font-family-nta: "nta", Arial, sans-serif;
 ///
 /// @type List
 /// @access public
-/// @deprecated Will be removed once support for GOV.UK Template/Elements is dropped
+/// @deprecated To be removed once support for compatibility mode is dropped
 
 $govuk-font-family-nta-tabular: "ntatabularnumbers", $govuk-font-family-nta;

src/settings/_typography-font.scss

@@ -53,7 +53,8 @@ $govuk-font-family-print: sans-serif !default;
 
 /// Include the default @font-face declarations
 ///
-/// If you have set $govuk-font-family to something other than $govuk-font-family-govuk-transport this option is disabled by default.
+/// If you have set $govuk-font-family to something other than
+/// `$govuk-font-family-govuk-transport` this option is disabled by default.
 ///
 /// @type Boolean
 /// @access public

src/settings/_typography-responsive.scss

@@ -5,15 +5,11 @@
 ////
 
 /// Whether or not to define font sizes in rem, improving accessibility by
-/// allowing users to adjust the base font-size. This is currently off by
-/// default, but will be enabled by default for projects that do not use
-/// alphagov/govuk_template in the next major release.
+/// allowing users to adjust the base font-size. This is enabled by default,
+/// unless any of the compatibility mode settings are enabled.
 ///
-/// If this is enabled, you should make sure that $govuk-root-font-size is set
-/// correctly for your project
-///
-/// If any of the compatibility variables are set, then default
-/// responsive typography to off.
+/// You should make sure that $govuk-root-font-size is set correctly for your
+/// project.
 ///
 /// @type Boolean
 /// @access public
@@ -34,8 +30,9 @@ $govuk-typography-use-rem: if((
 /// should be set to 16px.
 ///
 /// If you are integrating Frontend into an existing project that also uses
-/// alphagov/govuk_template then you should set this to 10px to match the 62.5%
-/// (10px) base font size that govuk_template sets on the <html> element.
+/// alphagov/govuk_template and you wish to enable `$govuk-typography-use-rem`
+/// then you should set this to 10px to match the 62.5% (10px) base font size
+/// that govuk_template sets on the <html> element.
 ///
 /// @type Number
 /// @access public