CSS utilities

Introduction

CSS utilities in this project provide repeatable styles that accomplish common tasks in a consistent way. Using the CSS utilities instead of one-off implementations makes behavior more consistent: for example, if a color needs to change it can be changed in only one place while remaining consistent, and using breakpoint utilities from the “media” utilities means that layouts will all shift at a common window width instead of at multiple different points.

Importing

Import utilities in any SCSS file by placing:

@use 'styles/utils';

at the top.

Now, the utils object will contain all of our CSS utilities, which you can use throughout the file.

Utilities

Colors

Color variables defined in utils/_colors.scss are available under the utils.color-* prefix. For example:

.element {
  background-color: utils.$color-deep-black;
  color: utils.$color-green;
  border: 1px solid utils.$color-white;
}

Typography

Includes utilities for applying styles from our type system. You can apply any of the styles to any element (for example, you can make an element that isn't an h3 take the h3 style anyway—this may be preferable in many cases, for example if an h3 doesn't make sense semantically, if an element needs to be a button for accessibility, etc.). These utilities are available under the utils.type-* prefix.

Example:

.selector {
  @include utils.type-h2;
}
.another-selector {
  @include utils.type-body-2;
}

Layout

The utils.layout-* utilities provide common implementations of many layout tasks.

vw units

Often, you may want to use a vw unit to make element sizes grow with the window width. However, it's worth noting that in our site, the layout stops growing horizontally after 1920px; after this point the main layout stays inside the same width and the margins around it simply grow. This ensures layouts don't look awkward on super wide screens. However, if you use the vw unit, the elements you size using vw will continue to grow even after the rest of the layout stops growing. If you use utils.capped-vw(<number>) instead, your element will grow only up to the point that the layout grows, and then stops. This is more desirable!

Before:

.element {
  margin-left: 5vw;
}

After:

.element {
  margin-left: utils.capped-vw(5);
}

“Full bleed” layouts

By default, all content is kept within healthy margins from the edge of the page. If you need an element to expand outside these margins (for example, to create a section with a different background color that expands all the way to the edges), you can use the full-bleed mixin as follows:

section.base {
  @include utils.layout-full-bleed;
  background-color: $some-crazy-color;
}

Now, the background color will extend all the way to the edges in the page, but the content inside our section.base element will still be padded the proper distance from the edges of the page.

Grid layouts

To create layouts on a twelve-column grid using CSS grid, @include utils.layout-twelve-columns (or, combine with the above by @include utils.layout-full-bleed-twelve-columns). Use these mixins on a container element; its children will become grid items. Check out this guide to CSS grid to learn how to control the children inside this grid environment.

Media queries

To create styles that only apply at certain window sizes, use the utils.media-* mixins.

.selector {
  @include utils.media-smallest {
    /* styles in here will only apply on small screens */
  }
}

Check out utils/_media.scss for the full set of available breakpoints and mixins. Using these utilities ensures that all site content changes layout at consistent breakpoints.