Tokens

Design tokens allow us to abstract CSS values into variables, rather than hard-coding them throughout our application.

Stitches provides first-class token support. You can see the offical stitches documentation on tokens here.

Defining tokens#

Tokens are defined in the theme.css.tsx file of your application.

The theme object within createStitches contains sets of tokens. The available token namespaces are:

• colors
• fonts
• fontSizes
• fontWeights
• lineHeights
• letterSpacings
• radii
• sizes
• space
• zIndices
• shadows
• transitions
• borderWidths
• borderStyles

You can technically add your own, too! For example, you could add a cursors object, which maps to a set of custom cursors.

Using Tokens#

There are two primary ways of using tokens within your project:

Shorthand Syntax#

The shorthand $tokenName syntax, which works within certain CSS properties.

For example, within padding and margin related CSS properties, you can use padding: "$1" to set the padding to spacing token #1. You can also use borderRadius: "$sm" to set the border radius to the predefined radii.sm value. This works, because Stitches knows which CSS property should use which theme token type.

You can see the default property mapping here.

Examples:

const Example = styled("div", {
  padding: "$3",
  color: "$fg",
})

Explicit Syntax#

You can also explicitly name the token set which you'd like to use, via $namespace$tokenName. This is only really necessary when deviating

For example, you can use borderRadius: "$space$1", which will use the space token set, even though the default token set for borderRadius is radii.

const Example = styled("div", {
  lineHeight: "$space$3",
  position: "absolute",
})