A17 SCSS Utilities

Description

Takes structure information from the config and generates a series of :root variables which are used by other A17 SCSS utilities.

Setup

Required setup for all plugins (except Color). Additional set up maybe required for other utilities.

_tokens.scss

$structure: (
  breakpoints: (
    xs: 0,
    sm: 544px,
    md: 650px,
    lg: 990px,
    xl: 1300px,
    xxl: 1520px
  ),
  container: (
    xs: auto,
    sm: auto,
    md: auto,
    lg: auto,
    xl: auto,
    xxl: 1440px
  ),
  columns: (
    xs: 4,
    sm: 4,
    md: 8,
    lg: 12,
    xl: 12,
    xxl: 12
  ),
  gutters: (
    inner: (
      xs: 10px,
      sm: 15px,
      md: 20px,
      lg: 30px,
      xl: 40px,
      xxl: 40px
    ),
    outer: (
      xs: 20px,
      sm: 30px,
      md: 40px,
      lg: 40px,
      xl: 40px,
      xxl: auto
    )
  )
);

And, so your application.scss will look like:

application.scss

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ include setup tokens

@import '_tokens';

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ include A17 SCSS Utilities

@import '~@area17/scss-utilities/a17-scss-utilities';

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ include site css

@import 'mixins/_your-mixin';

Breakdown

_tokens.scss

$structure: (
  breakpoints: (
    xs: 0,
    sm: 544px,
    md: 650px,
    lg: 990px,
    xl: 1300px,
    xxl: 1520px
  ),
);

A key-value SCSS map of your breakpoints, where the keys are your breakpoint names and the values are the start points of the breakpoints.

For the following SCSS maps, it probably helps to define "design grid". We call the grid that the design system lives within, as opposed to CSS Grid or a grid layout. Of course, you may then make components that use CSS Grid to make a grid layout which lives on the design grid.

And so, referencing the screen shot above:

container is the defined as the area the blue bars cover;
columns are the blue bars
gutters
- inner - the gaps between blue bars
- outer - the gaps on the outside of the first and last blue bar

_tokens.scss

$structure: (
  container: (
    xs: auto,
    sm: auto,
    md: auto,
    lg: auto,
    xl: auto,
    xxl: 1440px
  ),
);

A key-value SCSS map describing the width of the main container at each breakpoint. Values can be auto for fluid width or a defined value to lock the column at a certain breakpoint. This allows you to build fluid and adaptive layouts.

_tokens.scss

$structure: (
  columns: (
    xs: 4,
    sm: 4,
    md: 8,
    lg: 12,
    xl: 12,
    xxl: 12
  ),
);

A key-value SCSS map describing how many design columns are at each breakpoint.

_tokens.scss

$structure: (
  gutters: (
    inner: (
      xs: 10px,
      sm: 15px,
      md: 20px,
      lg: 30px,
      xl: 40px,
      xxl: 40px
    ),
    outer: (
      xs: 20px,
      sm: 30px,
      md: 40px,
      lg: 40px,
      xl: 40px,
      xxl: auto
    )
  )
);

Two key-value SCSS maps describing the design grid inner and outer gutters, per breakpoint. Can be a auto (when the container has a fixed width at a breakpoint) or a defined value (for other breakpoints).

Output

Based on the reference config mentioned in this guide, we would get the following in our CSS:

app.css

:root {
  --breakpoint: "xs";
  --container-width: unset;
  --inner-gutter: 10px;
  --outer-gutter: 20px;
  --grid-columns: 4;
}

@media (min-width: 544px) {
  :root {
    --breakpoint: "sm";
    --container-width: unset;
    --inner-gutter: 15px;
    --outer-gutter: 30px;
    --grid-columns: 4;
  }
}

@media (min-width: 650px) {
  :root {
    --breakpoint: "md";
    --container-width: unset;
    --inner-gutter: 20px;
    --outer-gutter: 40px;
    --grid-columns: 8;
  }
}

@media (min-width: 990px) {
  :root {
    --breakpoint: "lg";
    --container-width: unset;
    --inner-gutter: 30px;
    --outer-gutter: 40px;
    --grid-columns: 12;
  }
}

@media (min-width: 1300px) {
  :root {
    --breakpoint: "xl";
    --container-width: unset;
    --inner-gutter: 40px;
    --outer-gutter: 40px;
    --grid-columns: 12;
  }
}

@media (min-width: 1520px) {
  :root {
    --breakpoint: "xxl";
    --container-width: 1440px;
    --inner-gutter: 40px;
    --outer-gutter: 0px;
    --grid-columns: 12;
  }
}

Notes

As these variables are on the :root, they are easily read by JavaScript. For example to know which is the currently active CSS breakpoint in JavaScript, you could read the --breakpoint variable:

application.js

window.getComputedStyle(document.body).getPropertyValue('--breakpoint');