Tokens

Interacting with our Design System

In earlier iterations of R&P, we essentially made our own token system to handle all design aspects of our websites, from typography and colour to site-wide spacing and box-shadows.

It was clever. It worked pretty well.

However, it wasn’t overly intuitive to new employees and the code ended up being fairly verbose with logic that was difficult to parse.

Then we stumbled across a brand new CSS-in-JS solution that utilized a css token system in a similar fashion, albeit more intuitively: Stitches.dev!

We weighed the pros and cons of adopting a brand new tech, but in the end we gave it a go. We haven't looked back since!

For a more in depth look at how tokens work in Stitches, you can reference the documentation here.

Once you're comfortable with the general idea, this article will further explain:

1. Where we keep our token files.

2. Where we inject the tokens.

3. How we use the tokens.

All of our token files are located in the Design/Tokens directory.

Some contain simple objects (radii, borders and zIndices), while others are more verbose (link, type and pinion).

Most are imported and used in the theme object, found in stitches.config.js.

There are 14 different token types that the stitches theme object utilizes. All we have to do is add them to the object after importing:

export const {
  styled,
  css,
  globalCss,
  keyframes,
  getCssText,
  theme,
  createTheme,
  config,
} = createStitches({
  theme: {
    colors,
    space,
    form,
    grid,
    shadows,
    duration,
    easing,
    transitions,
    sizes,
    radii,
    zIndices,
    borderWidths,
    borders,
    breakpoints,
    ...spacing,
    ...magicNumbers,
    ...type,
  },

During the development process we will sometimes find that the styles become quite complicated, with multiple variants.

To keep our component files slimmer, we throw the styles in the tokens directory as well, and import them instead.

For an example, consider checking out the Text and Link components.

Once the tokens have been added to stitches.config.js, they are readily available for use throughout our project!

When it comes time to creating styles for our components, you use the tokens by prefixing them with a $ in your CSS declarations:

const $Example = styled('div', {
  w: '100%',
  h: '100%',
  bc: '$lightBlue',
  border: '$thin',
  boxShadow: '$m',
  borderRadius: '$round',
});

There are a few important things to remember when styling with Stitches:

1. Stitches has default property mapping.

95% of the time it's intuitive, but every once in a while you may find yourself using a token that doesn't actually work with that css property correctly. This is also the case within CSS functions, such as calc.

To work around this, make sure you specify the scope the token exists within, like so:

// Using colour tokens in border:
border: '1px solid $colors$purple500'

// Scoping tokens in CSS functions:
max-width: 'calc(5rem - $space$3)'

2. We have some custom CSS properties that we've defined through the use of Stitches utils.

Align and type are two such examples.

Because they're functions, they accept a plain string as an argument, and not a token value:

// This won't work:
align: '$left';

// This works!
align: 'left';