Utils

Making Objects for Stitches

All of the files located in the Design/Utils directory contain functions that either:

1. Help make objects that can used to define tokens used in stitches.config.js.

2. Make custom css properties that yield their own specific CSS.

Let's give an example of each below.

Let's take a look at space.js.

The sole purpose of the getSpace function in this file is to create an object containing a key that is a number and an associated rem value:

// Yes, we have a system for including half-values!
{
  1: '0.5rem',
  1_5: '0.75rem',
  2: '1rem',
  2_5: '1.25rem',
  3: '1.5rem',
  ...,
}

There are some default arguments that are provided, but these get overriden or customized by the space.js file in the Design/Tokens directory, where this function is actually imported and called.

FINALLY, this object is included as part of the theme object in stitches.config.js, allowing us to use the tokens in our CSS.

Here's an example of how we would use the space tokens:

// By default, stitches will map these tokens to
// css properties that are more or less intuitive (padding, margin, etc).

const Example = styled('div', {
  d: 'flex',
  jc: 'center',
  p: '$4', // 32px of padding all around.
  mt: '$2', // 16px of top margin.
});

Other functions, such as those found in ratio, align and box, ultimately return specific CSS based upon the argument their supplied with.

If you check out stitches.config.js and scroll to the bottom, you'll find these custom functions used in the utils object:

utils: {
    ...utils, // These are all the short-hand properties (Design/tokens/utils.js)
    box: (values) => getBoxSpacing(values),
    align: (values) => getAlignment(values),
    ratio: (ratio) => getRatioStyles(ratio),
    type: (variant) => getType(variant),
    typeSizes: (variant) => getTypeSizes(variant),
    typeStyles: (variant) => getTypeStyles(variant),
  },

If we use ratio as an example, it passes an argument to getRatioStyles, which pulls out the height and width from the ratio string and applies it as padding-bottom to a before pseudoelement. This is useful for adding a placeholder that prevents layout shift while the image loads:

export const getRatioStyles = (ratio) => {
  const [width, height] = ratio.split(':');
  return {
    '&::before': {
      content: '',
      d: 'block',
      w: '100%',
      pb: `${(height / width) * 100}%`,
    },
  };
};

In practice, it would look something like this:

const $Image = styled('img', {
  ratio: '4:3',
});

Yes, there are a lot of different utils files found throughout the Design directory. This can get a little confusing.

Just remember that these ones, located in the Utils directory, are the guys that do all the work behind the scenes.

They're either imported and used in the tokens files as helpers, or directly in stitches.config.js, in the case of extending the utils object.