@apolitical/component-library 1.18.8 → 2.0.0

package/styles/README.md

@@ -1,5 +1,11 @@
 # Styles
 
+- [`@layer](#layer)
+- [Colour variables](#colour-variables)
+- [`button` styling](#button-styling)
+
+---
+
 ## `@layer`
 
 We're using [CSS cascade layers (`@layer`)](https://www.smashingmagazine.com/2022/01/introduction-css-cascade-layers/) to organise our styles, to help us avoid specificity issues and to make it easier to find and update styles.
@@ -8,6 +14,28 @@ The `public/styles/index.scss` file defines the order of our layers, with the br
 
 If you need to overwrite CSS, you don't need to create an overly specific (and less performant) rule or add an `!important` (as an aside: please, please [never add an `!important`](https://dev.to/alvaromontoro/using-important-in-css-75c)) - just put the styling in a higher layer.
 
+The only 'gotcha' with this is importing external CSS; any styling that _isn't_ in a CSS layer is considered more important than styling in CSS layers, so styling from an external package will overwrite our styling. To change this, we need to write any styling that needs to overwrite external styling outside of CSS layers. (See the `InviteForm` component for an example.)
+
+---
+
+## Colour variables
+
+Our colour variables are defined in `public/styles/variables/colors`.
+
+We have two separate files:
+
+- `colors.scss` defines the colours themselves, using the names as they're defined in Figma, like `b700`. **We never call these values directly in the code.**
+
+Because the colours are described as colours (`b700`), rather than by what they're used for (`link_hover`), we can't rely on these names. In a future redesign, the links might become pale pink - at which point `b700` would no longer make sense, and would make the code hard to read and reason about. We also can't guarantee that everything which used to be `b700` is now pink in the redesign - some things may become yellow or green instead.
+
+We can't rely on these colours making sense in the future, so we don't use them directly in the code.
+
+- `theme/index.scss` defines a `$theme` map which describes where the colours are used, rather than what the colours look like, e.g. `card_bg` for the default background colour of cards and `card_hover_bg` for the background colour cards should change to on hover.
+
+Using these names, rather than the direct colour values, future-proofs the code against redesigns and makes it easy to maintain; when we redesign the platform, we can update the colours in one place, rather than having to amend every component.
+
+To avoid `theme` being a giant, difficult-to-navigate file, we split out all the values by the component directory they're in (e.g. `base`, `buttons`, `cards`, etc.) and then import them into `theme/index.scss`. We use a Sass function to pull everything into the `$theme` variable, so we don't need to know exactly what's in each file.
+
 ---
 
 ## `button` styling

package/styles/base/_accessibility.scss

@@ -1,19 +1,30 @@
-@use 'sass:map';
-@import './../functions',
-        './../mixins',
-        './../variables';
+@import './../functions', './../mixins', './../variables';
 
 @layer base {
-  a, button, input, textarea, [role="menu"], li[tabindex] {
-    &:focus, &:focus-visible {
+  a,
+  button,
+  input,
+  textarea,
+  [role='menu'],
+  li[tabindex] {
+    &:focus,
+    &:focus-visible {
       outline: none;
-      box-shadow: $outline map.get($theme, 'default_focus');
+      box-shadow: $outline get-map($theme, 'default_focus');
+    }
+
+    &:active {
+      box-shadow: none;
     }
-    &:active { box-shadow: none; }
   }
 
-  [role="menu"], [role="menu"] a, li[tabindex] {
-    &:focus, &:focus-visible { box-shadow: $outline map.get($theme, 'default_focus') inset; }
+  [role='menu'],
+  [role='menu'] a,
+  li[tabindex] {
+    &:focus,
+    &:focus-visible {
+      box-shadow: $outline get-map($theme, 'default_focus') inset;
+    }
   }
 
   .hidden {
@@ -23,4 +34,3 @@
     overflow: hidden;
   }
 }
-

package/styles/base/_blockquotes.scss

@@ -1,29 +1,40 @@
-@use 'sass:map';
-@import './../functions',
-        './../mixins',
-        './../variables';
+@import './../functions', './../mixins', './../variables';
 
-$blockquote: ('margin-top': 20, 'margin-top_md': 30, 'margin-bottom': 10, 'margin-bottom_md': 20, 'padding-vertical': 4, 'padding-left': 24, 'font-size': 18, 'font-size_md': 20, 'line-height': 28, 'border-width': 6);
+$blockquote: (
+  'margin-top': 20,
+  'margin-top_md': 30,
+  'margin-bottom': 10,
+  'margin-bottom_md': 20,
+  'padding-vertical': 4,
+  'padding-left': 24,
+  'font-size': 18,
+  'font-size_md': 20,
+  'line-height': 28,
+  'border-width': 6,
+);
 
 @layer base {
   blockquote {
-    margin: px-to-rem(map.get($blockquote, 'margin-top')) 0 px-to-rem(map.get($blockquote, 'margin-bottom')) 0;
-    padding: px-to-rem(map.get($blockquote, 'padding-vertical')) 0 0 px-to-rem(map.get($blockquote, 'padding-left'));
-    font-size: px-to-rem(map.get($blockquote, 'font-size'));
-    color: map.get($theme, 'blockquote');
+    margin: px-to-rem(get-map($blockquote, 'margin-top')) 0
+      px-to-rem(get-map($blockquote, 'margin-bottom')) 0;
+    padding: px-to-rem(get-map($blockquote, 'padding-vertical')) 0 0
+      px-to-rem(get-map($blockquote, 'padding-left'));
+    font-size: px-to-rem(get-map($blockquote, 'font-size'));
+    color: get-map($theme, 'blockquote');
     font-weight: 700;
     font-style: italic;
-    line-height: px-to-rem(map.get($blockquote, 'line-height'));
-    border-left: px-to-rem(map.get($blockquote, 'border-width')) solid map.get($theme, 'blockquote_border');
+    line-height: px-to-rem(get-map($blockquote, 'line-height'));
+    border-left: px-to-rem(get-map($blockquote, 'border-width')) solid
+      get-map($theme, 'blockquote_border');
 
-      p:last-of-type {
-        margin-bottom: 0;
-      }
+    p:last-of-type {
+      margin-bottom: 0;
+    }
 
-      @include breakpoint('min-width', 'md') {
-        margin-top: px-to-rem(map.get($blockquote, 'margin-top_md'));
-        margin-bottom: px-to-rem(map.get($blockquote, 'margin-bottom_md'));
-        font-size: px-to-rem(map.get($blockquote, 'font-size_md'));
-      }
+    @include breakpoint('min-width', 'md') {
+      margin-top: px-to-rem(get-map($blockquote, 'margin-top_md'));
+      margin-bottom: px-to-rem(get-map($blockquote, 'margin-bottom_md'));
+      font-size: px-to-rem(get-map($blockquote, 'font-size_md'));
+    }
   }
-}
+}

package/styles/base/_fonts.scss

@@ -26,16 +26,20 @@ $font-name: 'Moderat';
   }
 }
 
-$font-family: (400, normal), (400, italic), (600, normal), (600, italic), (900, normal), (900, italic);
-
+$font-family: (400, normal), (400, italic), (600, normal), (600, italic), (900, normal),
+  (900, italic);
 
 @layer base {
   @each $weight, $style in $font-family {
     @include font-styling($weight, $style);
   }
 
-  body, button, input, textarea {
-    font-family: #{$font-name}, sans-serif;
+  body,
+  button,
+  input,
+  textarea {
+    font-family:
+      #{$font-name},
+      sans-serif;
   }
-
-}
+}

package/styles/base/_hr.scss

@@ -1,16 +1,17 @@
-@use 'sass:map';
-@import './../functions',
-        './../variables';
+@import './../functions', './../variables';
 
-$hr: ('height': 1, 'margin-vertical': 40);
+$hr: (
+  'height': 1,
+  'margin-vertical': 40,
+);
 
 @layer base {
   hr {
     width: 100%;
-    height: px-to-rem(map.get($hr, 'height'));
-    background: map.get($theme, 'divider');
-    margin: px-to-rem(map.get($hr, 'margin-vertical')) auto;
+    height: px-to-rem(get-map($hr, 'height'));
+    background: get-map($theme, 'divider');
+    margin: px-to-rem(get-map($hr, 'margin-vertical')) auto;
     border: none;
     display: block;
   }
-}
+}

package/styles/base/_index.scss

@@ -1,13 +1,2 @@
-@import 'fonts',
-        'accessibility',
-        'blockquotes',
-        'buttons',
-        'form',
-        'hr',
-        'layout',
-        'links',
-        'lists',
-        'overlays',
-        'table',
-        'text',
-        'titles';
+@import 'fonts', 'accessibility', 'blockquotes', 'buttons', 'form', 'hr', 'layout',
+  'links', 'lists', 'overlays', 'table', 'text', 'titles';

package/styles/base/_layout.scss

@@ -1,12 +1,13 @@
-@import './../functions',
-  './../variables';
+@import './../functions', './../variables';
 
 @layer base {
-  [hidden] {  display: none;}
+  [hidden] {
+    display: none;
+  }
 
   .content-slim {
     max-width: px-to-rem($content-slim-width);
     margin-left: auto;
     margin-right: auto;
   }
-}
+}

package/styles/base/_links.scss

@@ -1,19 +1,17 @@
-@use 'sass:map';
-@import './../mixins',
-        './../variables';
+@import './../mixins', './../variables';
 
 @layer base {
   a {
-      @include transition(color text-decoration-color);
+    @include transition(color text-decoration-color);
 
-      color: map.get($theme, 'link');
-      text-decoration: underline;
-      font-weight: 900;
+    color: get-map($theme, 'link');
+    text-decoration: underline;
+    font-weight: 900;
 
-      &:hover,
-      &:focus,
-      &:active {
-        color: map.get($theme, 'link_hover');
-      }
+    &:hover,
+    &:focus,
+    &:active {
+      color: get-map($theme, 'link_hover');
+    }
   }
-}
+}

package/styles/base/_lists.scss

@@ -1,27 +1,40 @@
-@use 'sass:map';
 @import './../functions';
 
-$ul: ('margin-bottom': 16, 'padding-left': 40);
-$li: ('margin-bottom': 18, 'margin-bottom_sm': 12, 'margin-bottom_md': 16);
+$ul: (
+  'margin-bottom': 16,
+  'padding-left': 40,
+);
+$li: (
+  'margin-bottom': 18,
+  'margin-bottom_sm': 12,
+  'margin-bottom_md': 16,
+);
 
 @layer base {
-  ol, ul {
-    margin: 0 0 px-to-rem(map.get($ul, 'margin-bottom')) 0;
-    padding-left: px-to-rem(map.get($ul, 'padding-left'));
+  ol,
+  ul {
+    margin: 0 0 px-to-rem(get-map($ul, 'margin-bottom')) 0;
+    padding-left: px-to-rem(get-map($ul, 'padding-left'));
     display: block;
   }
 
   li {
-    margin-bottom: px-to-rem(map.get($li, 'margin-bottom'));
+    margin-bottom: px-to-rem(get-map($li, 'margin-bottom'));
 
-      .text-small & { margin-bottom: px-to-rem(map.get($li, 'margin-bottom_sm')); }
+    .text-small & {
+      margin-bottom: px-to-rem(get-map($li, 'margin-bottom_sm'));
+    }
 
-      .text-medium & { margin-bottom: px-to-rem(map.get($li, 'margin-bottom_md')); }
+    .text-medium & {
+      margin-bottom: px-to-rem(get-map($li, 'margin-bottom_md'));
+    }
 
-      &:last-child {
-        margin-bottom: 0;
+    &:last-child {
+      margin-bottom: 0;
 
-          p:last-child { margin-bottom: 0; }
+      p:last-child {
+        margin-bottom: 0;
       }
+    }
   }
-}
+}

package/styles/base/_overlays.scss

@@ -1,19 +1,20 @@
-@use 'sass:map';
-@import './../functions',
-        './../mixins',
-        './../variables';
+@import './../functions', './../mixins', './../variables';
 
-$overlay: ('padding': 48);
+$overlay: (
+  'padding': 48,
+);
 
 @layer base {
-  body.has-overlay { overflow: hidden; }
+  body.has-overlay {
+    overflow: hidden;
+  }
 
   .overlay {
     @include transition(opacity, 0.1s, ease);
 
     width: 0;
     height: 0;
-    background: map.get($theme, 'overlay');
+    background: get-map($theme, 'overlay');
     position: fixed;
     top: 0;
     left: 0;
@@ -25,35 +26,36 @@ $overlay: ('padding': 48);
     align-items: center;
     overflow: hidden;
 
-      &.open {
-        width: 100vw;
-        height: 100vh;
-        opacity: 1;
-        z-index: 998;
-      }
-
-      > div, > section {
-        width: 100vw;
-        height: 100vh;
-        margin-top: auto;
-        margin-bottom: auto;
-        overflow: hidden auto;
-      }
+    &.open {
+      width: 100vw;
+      height: 100vh;
+      opacity: 1;
+      z-index: 998;
+    }
 
+    > div,
+    > section {
+      width: 100vw;
+      height: 100vh;
+      margin-top: auto;
+      margin-bottom: auto;
+      overflow: hidden auto;
+    }
   }
 
   @include breakpoint('min-width', 'sm') {
     .overlay {
-        &.open {
-          padding: px-to-rem(map.get($overlay, 'padding'));
-          overflow-y: auto;
-        }
-
-        > div, > section {
-          width: auto;
-          height: auto;
-          overflow: unset;
-        }
+      &.open {
+        padding: px-to-rem(get-map($overlay, 'padding'));
+        overflow-y: auto;
+      }
+
+      > div,
+      > section {
+        width: auto;
+        height: auto;
+        overflow: unset;
+      }
     }
   }
-}
+}

package/styles/base/_table.scss

@@ -1,61 +1,74 @@
-@use 'sass:map';
-@import './../functions',
-        './../variables';
+@import './../functions', './../variables';
 
-$table: ('margin-top': 64, 'margin-bottom': 32, 'padding-vertical': 12, 'padding-horizontal': 20, 'border': 1, 'border-radius': 8);
+$table: (
+  'margin-top': 64,
+  'margin-bottom': 32,
+  'padding-vertical': 12,
+  'padding-horizontal': 20,
+  'border': 1,
+  'border-radius': 8,
+);
 
 @layer base {
   table {
     width: 100%;
-    margin: px-to-rem(map.get($table, 'margin-top')) auto px-to-rem(map.get($table, 'margin-bottom')) auto;
+    margin: px-to-rem(get-map($table, 'margin-top')) auto
+      px-to-rem(get-map($table, 'margin-bottom')) auto;
     border-collapse: separate;
     border-spacing: 0;
 
-      &, p, li { text-align: left; }
+    &,
+    p,
+    li {
+      text-align: left;
+    }
   }
 
-  th, td {
-    border: px-to-rem(map.get($table, 'border')) solid map.get($theme, 'table_border');
+  th,
+  td {
+    border: px-to-rem(get-map($table, 'border')) solid get-map($theme, 'table_border');
     vertical-align: top;
   }
 
-  th, tbody:first-child tr:first-child td {
-    background: map.get($theme, 'table_th_bg');
-    padding: px-to-rem(map.get($table, 'padding-horizontal'));
-    color: map.get($theme, 'table_th');
+  th,
+  tbody:first-child tr:first-child td {
+    background: get-map($theme, 'table_th_bg');
+    padding: px-to-rem(get-map($table, 'padding-horizontal'));
+    color: get-map($theme, 'table_th');
     font-weight: 600;
     border-right-width: 0;
 
-      /* Add border radius to the corners of the table, not each cell */
-      &:first-child {
-        border-top-left-radius: px-to-rem(map.get($table, 'border-radius'));
-      }
+    /* Add border radius to the corners of the table, not each cell */
+    &:first-child {
+      border-top-left-radius: px-to-rem(get-map($table, 'border-radius'));
+    }
 
-      &:last-child {
-        border-top-right-radius: px-to-rem(map.get($table, 'border-radius'));
-        border-right-width: px-to-rem(map.get($table, 'border'));
-      }
+    &:last-child {
+      border-top-right-radius: px-to-rem(get-map($table, 'border-radius'));
+      border-right-width: px-to-rem(get-map($table, 'border'));
+    }
   }
 
   td {
-    padding: px-to-rem(map.get($table, 'padding-vertical')) px-to-rem(map.get($table, 'padding-horizontal'));
+    padding: px-to-rem(get-map($table, 'padding-vertical'))
+      px-to-rem(get-map($table, 'padding-horizontal'));
     border-top-width: 0;
     border-right-width: 0;
 
-      /* Prevent borders with double width due to using border-collapse separate */
-      &:last-child {
-        border-right-width: px-to-rem(map.get($table, 'border'));
-      }
+    /* Prevent borders with double width due to using border-collapse separate */
+    &:last-child {
+      border-right-width: px-to-rem(get-map($table, 'border'));
+    }
   }
 
   tr:last-child {
     td {
       &:first-child {
-        border-bottom-left-radius: px-to-rem(map.get($table, 'border-radius'));
+        border-bottom-left-radius: px-to-rem(get-map($table, 'border-radius'));
       }
 
       &:last-child {
-        border-bottom-right-radius: px-to-rem(map.get($table, 'border-radius'));
+        border-bottom-right-radius: px-to-rem(get-map($table, 'border-radius'));
       }
     }
   }