From 0d68b4cd3c3aecec4428a71fd6bb5e7193b8c064 Mon Sep 17 00:00:00 2001
From: Casey Williams <caseywilliams@users.noreply.github.com>
Date: Thu, 13 Feb 2020 13:12:15 -0800
Subject: [PATCH] (PDS-442) Add breakpoint tools to sass-variables

Adds variables and mixins to the `sass-variables` package to allow for
configuring and responding to different breakpoints.

There are three breakpoints -- small, medium, and large -- which
correspond roughly to phone, tablet, and desktop widths.

Default breakpoints can be overridden by defining your own
`$breakpoints` map in your stylesheets before importing styles from the
design system.

Two mixins are included:

- `respond-above` applies styles to widths above the given size
- `respond-below` applies styles to widths below the given size
---
 .../foundations/Responsiveness.md             | 60 +++++++++++++++++++
 .../styleguide.config.js                      |  4 ++
 packages/sass-variables/_index.scss           |  1 +
 packages/sass-variables/_responsive.scss      | 25 ++++++++
 4 files changed, 90 insertions(+)
 create mode 100644 packages/design-system-website/foundations/Responsiveness.md
 create mode 100644 packages/sass-variables/_responsive.scss

diff --git a/packages/design-system-website/foundations/Responsiveness.md b/packages/design-system-website/foundations/Responsiveness.md
new file mode 100644
index 000000000..fa6264f05
--- /dev/null
+++ b/packages/design-system-website/foundations/Responsiveness.md
@@ -0,0 +1,60 @@
+## Overview
+
+This system remains mostly unopinionated on responsive tools, but the `sass-variables` package contains a few mixins to help you customize your own styles based on the viewport width:
+
+* `respond-above` applies styles only above a certain width. For example, the following constrains the width of `.container` elements, but only on larger screens:
+    ```scss
+    .container {
+        width: 100%;
+
+        @include respond-above(large) {
+          width: 1180px;
+        }
+    }
+    ```
+* `respond-below` applies styles only below a certain width. Here's an equivalent example using `respond-below` instead:
+    ```scss
+    .container {
+      width: 1180px;
+  
+      @include respond-below(large) {
+        width: 100%;
+      }
+    } 
+    ```
+
+### Breakpoint widths
+
+The mixins respond to three sizes by default:
+
+- `small` (most phone screens)
+- `medium` (most tablets, small browser windows)
+- `large` (browser windows)
+
+You can customize these values or add your own by redefining the `$breakpoints` map variable in your SCSS before you include the design system styles. Here's an example:
+
+```scss
+// Define your breakpoint map:
+$breakpoints: (
+  'small': 576px,
+  'medium': 768px,
+  'large': 992px,
+  'xlarge': 1180px
+); 
+
+// Import design system stylesheets after your breakpoint definitions:
+@import '~@puppet/sass-variables/index';
+
+.container {
+  @include respond-above(xlarge) {
+    // Now responds above 1180px
+  }
+}
+```
+
+### Which mixin should I use?
+
+The conventional wisdom of "mobile-first" design encourages designing at the smallest widths first, then progressively enhancing the design for larger sizes. This tends to improve the responsiveness of the design overall, since it forces a focus on multiple sizes from the beginning.
+
+We suggest writing your initial styles for smaller screen widths, then using `respond-above` to adapt them to larger screens. `respond-below` is included as a convenience.
+
diff --git a/packages/design-system-website/styleguide.config.js b/packages/design-system-website/styleguide.config.js
index 1edd3e511..72d0bd623 100644
--- a/packages/design-system-website/styleguide.config.js
+++ b/packages/design-system-website/styleguide.config.js
@@ -87,6 +87,10 @@ module.exports = {
           name: 'Iconography',
           content: 'foundations/Iconography.md',
         },
+        {
+          name: 'Responsiveness',
+          content: 'foundations/Responsiveness.md',
+        },
         {
           name: 'Typography',
           content: 'foundations/Typography.md',
diff --git a/packages/sass-variables/_index.scss b/packages/sass-variables/_index.scss
index 62930f214..b5e6dbc83 100644
--- a/packages/sass-variables/_index.scss
+++ b/packages/sass-variables/_index.scss
@@ -2,3 +2,4 @@
 @import './common';
 @import './fonts';
 @import './typography';
+@import './responsive';
diff --git a/packages/sass-variables/_responsive.scss b/packages/sass-variables/_responsive.scss
new file mode 100644
index 000000000..e0f474f62
--- /dev/null
+++ b/packages/sass-variables/_responsive.scss
@@ -0,0 +1,25 @@
+$breakpoints: (
+  'small': 576px,
+  'medium': 768px,
+  'large': 992px,
+) !default;
+
+@mixin respond-above($breakpoint) {
+  @if map-has-key($breakpoints, $breakpoint) {
+    @media (min-width: map-get($breakpoints, $breakpoint)) {
+      @content;
+    }
+  } @else {
+    @warn "Unrecognized breakpoint '#{$breakpoint}'. Available breakpoints are: #{map-keys($breakpoints)}.";
+  }
+}
+
+@mixin respond-below($breakpoint) {
+  @if map-has-key($breakpoints, $breakpoint) {
+    @media (max-width: map-get($breakpoints, $breakpoint) - 1) {
+      @content;
+    }
+  } @else {
+    @warn "Unrecognized breakpoint '#{$breakpoint}'. Available breakpoints are: #{map-keys($breakpoints)}.";
+  }
+}