Turn off compatibility mode by default and turn on relative typography (rem) by default

CHANGELOG.md

@@ -72,6 +72,43 @@
 
   ([PR #969](https://github.com/alphagov/govuk-frontend/pull/969))
 
+- Turn off [compatibility mode](./docs/installation/installing-with-npm.md#compatibility-mode) by default for [GOV.UK Elements](https://github.com/alphagov/govuk_elements), [GOV.UK Template](https://github.com/alphagov/govuk_template), [GOV.UK Frontend Toolkit](https://github.com/alphagov/govuk_frontend_toolkit)
+
+  You do not need to make any changes if you do not use these projects alongside GOV.UK Frontend.
+
+  To migrate include the SCSS variables that correspond with the projects you depend on before importing GOV.UK Frontend styles into your app:
+
+  ```SCSS
+  // application.scss
+  $govuk-compatibility-govukfrontendtoolkit: true;
+  $govuk-compatibility-govuktemplate: true;
+  $govuk-compatibility-govukelements: true;
+  @import "govuk-frontend/all";
+  ```
+  ([PR #981](https://github.com/alphagov/govuk-frontend/pull/981))
+
+- Turn on relative typography (rem) by default
+
+  This allows for end-users to adjust GOV.UK Frontend components by setting their font size in their browser.
+
+  If you are using GOV.UK Frontend on with no other frameworks this should not break your project.
+
+  If you need to change this setting for compatibility with [GOV.UK Elements](https://github.com/alphagov/govuk_elements), [GOV.UK Template](https://github.com/alphagov/govuk_template), [GOV.UK Frontend Toolkit](https://github.com/alphagov/govuk_frontend_toolkit) consider enabling [compatibility mode](./docs/installation/installing-with-npm.md#compatibility-mode).
+
+  Otherwise, set `$govuk-typography-use-rem` to `false` before importing GOV.UK Frontend styles into your app:
+  ```SCSS
+  // application.scss
+  $govuk-typography-use-rem: false;
+  @import "govuk-frontend/all";
+  ```
+  ([PR #981](https://github.com/alphagov/govuk-frontend/pull/981))
+
+- Pull Request Title goes here
+
+  Description goes here (optional)
+
+  ([PR #N](https://github.com/alphagov/govuk-frontend/pull/N))
+
 🆕 New features:
 
 - Pull Request Title goes here

docs/installation/installing-with-npm.md

@@ -41,14 +41,14 @@ imports) if you want to override GOV.UK Frontend with your own styles.
 
 1. To import all components, add the below to your Sass file:
 
-  ```CSS
+  ```SCSS
   @import "node_modules/govuk-frontend/all";
   ```
 
 2. To import an individual component (for example a button), add the below to
 your Sass file:
 
-  ```CSS
+  ```SCSS
   @import "node_modules/govuk-frontend/components/button/button";
   ```
 
@@ -81,7 +81,7 @@ to include add `includePaths` to it.
 
 After resolving the import paths you can import GOV.UK Frontend by using:
 
-```CSS
+```SCSS
 @import "govuk-frontend/components/button/button";
 ```
 
@@ -95,14 +95,31 @@ Hovever, we do include some global styles in the [GOV.UK Prototype Kit](https://
 
 These [global styles](../../src/core/_global-styles.scss) are are not included by default in GOV.UK Frontend. To include these global styles in your app, you can set `$govuk-global-styles` variable to `true` before importing GOV.UK Frontend styles into your app:
 
-```
+```SCSS
 // application.scss
 
 $govuk-global-styles: true;
 
 @import "govuk-frontend/all";
 ```
 
+### Compatibility mode
+GOV.UK Frontend includes additional styles that can be enabled to allow support for deprecated projects such as [GOV.UK Elements](https://github.com/alphagov/govuk_elements), [GOV.UK Template](https://github.com/alphagov/govuk_template), [GOV.UK Frontend Toolkit](https://github.com/alphagov/govuk_frontend_toolkit).
+
+Setting compatibility SCSS variables will change how GOV.UK Frontend's CSS renders to work around global styles that conflict with GOV.UK Frontend.
+
+To enable this feature include the SCSS variables that correspond with the projects you depend on before importing GOV.UK Frontend styles into your app:
+
+```SCSS
+// application.scss
+
+$govuk-compatibility-govukfrontendtoolkit: true;
+$govuk-compatibility-govuktemplate: true;
+$govuk-compatibility-govukelements: true;
+
+@import "govuk-frontend/all";
+```
+
 ## Using JavaScript
 
 Some of the JavaScript included in GOV.UK Frontend improves the usability and

src/helpers/typography.test.js

@@ -14,11 +14,10 @@ const sassConfig = {
 }
 
 const sassBootstrap = `
+  @import "settings/compatibility";
   @import "settings/media-queries";
   @import "settings/ie8";
-
-  $govuk-root-font-size: 16px;
-  $govuk-typography-use-rem: false;
+  @import "settings/typography-responsive";
 
   $govuk-breakpoints: (
     desktop: 30em
@@ -112,10 +111,12 @@ describe('@mixin govuk-typography-responsive', () => {
     expect(results.css.toString().trim()).toBe(outdent`
       .foo {
         font-size: 12px;
+        font-size: 0.75rem;
         line-height: 1.25; }
         @media (min-width: 30em) {
           .foo {
             font-size: 14px;
+            font-size: 0.875rem;
             line-height: 1.42857; } }`)
   })
 
@@ -132,6 +133,7 @@ describe('@mixin govuk-typography-responsive', () => {
     expect(results.css.toString().trim()).toBe(outdent`
       .foo {
         font-size: 12px;
+        font-size: 0.75rem;
         line-height: 1.25; }
         @media print {
           .foo {
@@ -168,10 +170,12 @@ describe('@mixin govuk-typography-responsive', () => {
       expect(results.css.toString().trim()).toBe(outdent`
         .foo {
           font-size: 12px !important;
+          font-size: 0.75rem !important;
           line-height: 1.25 !important; }
           @media (min-width: 30em) {
             .foo {
               font-size: 14px !important;
+              font-size: 0.875rem !important;
               line-height: 1.42857 !important; } }`)
     })
 
@@ -188,6 +192,7 @@ describe('@mixin govuk-typography-responsive', () => {
       expect(results.css.toString().trim()).toBe(outdent`
         .foo {
           font-size: 12px !important;
+          font-size: 0.75rem !important;
           line-height: 1.25 !important; }
           @media print {
             .foo {
@@ -210,19 +215,21 @@ describe('@mixin govuk-typography-responsive', () => {
       expect(results.css.toString().trim()).toBe(outdent`
         .foo {
           font-size: 12px;
+          font-size: 0.75rem;
           line-height: 1.75; }
           @media (min-width: 30em) {
             .foo {
               font-size: 14px;
+              font-size: 0.875rem;
               line-height: 1.5; } }`)
     })
   })
 
-  describe('when $govuk-typography-use-rem is enabled', () => {
+  describe('when $govuk-typography-use-rem is disabled', () => {
     it('outputs CSS with suitable media queries', async () => {
       const sass = `
+        $govuk-typography-use-rem: false;
         ${sassBootstrap}
-        $govuk-typography-use-rem: true;
 
         .foo {
           @include govuk-typography-responsive($size: 14)
@@ -233,20 +240,18 @@ describe('@mixin govuk-typography-responsive', () => {
       expect(results.css.toString().trim()).toBe(outdent`
         .foo {
           font-size: 12px;
-          font-size: 0.75rem;
           line-height: 1.25; }
           @media (min-width: 30em) {
             .foo {
               font-size: 14px;
-              font-size: 0.875rem;
               line-height: 1.42857; } }`)
     })
 
     it('adjusts rem values based on root font size', async () => {
       const sass = `
-        ${sassBootstrap}
-        $govuk-typography-use-rem: true;
+        $govuk-typography-use-rem: false;
         $govuk-root-font-size: 10px;
+        ${sassBootstrap}
 
         .foo {
           @include govuk-typography-responsive($size: 14)
@@ -257,20 +262,18 @@ describe('@mixin govuk-typography-responsive', () => {
       expect(results.css.toString().trim()).toBe(outdent`
         .foo {
           font-size: 12px;
-          font-size: 1.2rem;
           line-height: 1.25; }
           @media (min-width: 30em) {
             .foo {
               font-size: 14px;
-              font-size: 1.4rem;
               line-height: 1.42857; } }`)
     })
 
     describe('and $important is set to true', () => {
       it('marks font size and line height as important', async () => {
         const sass = `
+          $govuk-typography-use-rem: false;
           ${sassBootstrap}
-          $govuk-typography-use-rem: true;
 
           .foo {
             @include govuk-typography-responsive($size: 14, $important: true);
@@ -281,14 +284,35 @@ describe('@mixin govuk-typography-responsive', () => {
         expect(results.css.toString().trim()).toBe(outdent`
           .foo {
             font-size: 12px !important;
-            font-size: 0.75rem !important;
             line-height: 1.25 !important; }
             @media (min-width: 30em) {
               .foo {
                 font-size: 14px !important;
-                font-size: 0.875rem !important;
                 line-height: 1.42857 !important; } }`)
       })
     })
   })
+
+  describe('when compatibility mode is set', () => {
+    it('$govuk-typography-use-rem is disabled by default', async () => {
+      const sass = `
+        $govuk-compatibility-govuktemplate: true;
+        ${sassBootstrap}
+
+        .foo {
+          @include govuk-typography-responsive($size: 14)
+        }`
+
+      const results = await sassRender({ data: sass, ...sassConfig })
+
+      expect(results.css.toString().trim()).toBe(outdent`
+        .foo {
+          font-size: 12px;
+          line-height: 1.25; }
+          @media (min-width: 30em) {
+            .foo {
+              font-size: 14px;
+              line-height: 1.42857; } }`)
+    })
+  })
 })

src/settings/_compatibility.scss

@@ -16,7 +16,7 @@
 /// @type Boolean
 /// @access public
 
-$govuk-compatibility-govukfrontendtoolkit: true !default;
+$govuk-compatibility-govukfrontendtoolkit: false !default;
 
 /// Compatibility Mode: alphagov/govuk_template
 ///
@@ -25,7 +25,7 @@ $govuk-compatibility-govukfrontendtoolkit: true !default;
 /// @type Boolean
 /// @access public
 
-$govuk-compatibility-govuktemplate: true !default;
+$govuk-compatibility-govuktemplate: false !default;
 
 /// Compatibility Mode: alphagov/govuk_elements
 ///
@@ -34,7 +34,7 @@ $govuk-compatibility-govuktemplate: true !default;
 /// @type Boolean
 /// @access public
 
-$govuk-compatibility-govukelements: true !default;
+$govuk-compatibility-govukelements: false !default;
 
 /// Compatibility Product Map
 ///

src/settings/_typography-responsive.scss

@@ -7,13 +7,19 @@
 /// default, but will be enabled by default for projects that do not use
 /// alphagov/govuk_template in the next major release.
 ///
-/// If you enable this, you should make sure that `$govuk-root-font-size` is set
-/// correctly for your project.
+/// If this is enabled, you should make sure that $govuk-root-font-size is set
+/// correctly for your project
 ///
 /// @type Boolean
 /// @access public
 
-$govuk-typography-use-rem: false !default;
+// If any of the compatibility variables are set, then default
+// responsive typography to off.
+$govuk-typography-use-rem: if((
+    $govuk-compatibility-govukfrontendtoolkit or
+    $govuk-compatibility-govuktemplate or
+    $govuk-compatibility-govukelements
+  ), false, true) !default;
 
 /// Root font size
 ///