Grid

Because Consistency is Key

When we receive a figma file from our designer, one of the first things we do is enable the grid layout view. Most of the time, it's based upon a 12-column system, with varying sizes of gutters between.

If you take a look at the grid.js file under Design/Utils, you'll see a bunch of functions calculating values (yay, math)!

We provide default grid values for width, the number of columns and the gutter width and calculate all values from that.

The two functions we're most concerned about are pxToRem and getColumnsWidth.

Both of these functions are imported to the grid.js file in Design/Tokens, where we supply them with the actual grid dimensions from the given design.

Did the designer increase the gutter widths from 24px to 32px? No matter - just hop into this file, make the change and you're good to go!

When we call the getColumnsWidth function, we create an object that looks like this:

{
  'cols1': value,
  'cols2': value,
  'cols3': value,
  ...
}

This object is imported into the sizes.js token file, where it is spread within the sizes object. We can now use these values directly when calculating dimensions of our components, as well as create tokens that refer to them for ease of use (e.g. content is equivalent to cols6).

You will often find yourself using the grid columns to set the max-width of a component:

// Using our utility shorthand properties:
const $Paragraph = styled('p', {
  w: '100%',
  mw: '$cols4',
});

🦶🔫 Footgun: The gutter to the right of the column is included when calculating the total size of the column!

The css calc function is our best friend if we find we need to remove the gutter in our final calculation.

For example, if the component needs a max-width of two columns minus the gutter, and we know the gutters are each 32px in width, we can write:

// We use the 8px grid model for our spacing values.
// Therefore, $space$4 is equivalent to 32px (4 * 8).
// When using tokens within a css function, you have to specify the
// theme object the value is scoped to, which is `space` in this case.

const $Paragraph = styled('p', {
  w: '100%',
  mw: 'calc($cols4 - $space$4)',
});

As you work through a project, you'll start to truly see how much we rely on these grid values.

Make sure that you update the grid values before you build your components. Otherwise, the default values will be used, yielding unexpected outcomes.