Tokens

Define reusable design tokens.

Defining tokens

You can define your tokens as part of the createStyled configuration. There are 14 token types available.

export const { styled, css } = createStyled({
  tokens: {
    colors: {
      $gray500: 'hsl(206,10%,76%)',
      $blue500: 'hsl(206,100%,50%)',
      $purple500: 'hsl(252,78%,60%)',
      $green500: 'hsl(148,60%,60%)',
      $red500: 'hsl(352,100%,62%)',
    },
    space: {
      $1: '5px',
      $2: '10px',
      $3: '15px',
    },
    fontSizes: {
      $1: '12px',
      $2: '13px',
      $3: '15px',
    },
    fonts: {
      $untitled: 'Untitled Sans, apple-system, sans-serif',
      $mono: 'Söhne Mono, menlo, monospace',
    },
    fontWeights: {},
    lineHeights: {},
    letterSpacings: {},
    sizes: {},
    borderWidths: {},
    borderStyles: {},
    radii: {},
    shadows: {},
    zIndices: {},
    transitions: {},
  },
});

This is based on the System UI Theme Specification by Brent Jackson.

Prefixing and naming

We highly recommend prefixing each token with $, @ or some other symbol.

Since many devs use a numeric scale for token names, and numeric values like 5 convert to 5px, non-prefixed tokens can cause confusion.

Prefixing all tokens ensures an accurate TypeScript autocomplete experience.

However, token prefixes are optional. They still work, but numeric scale tokens will autocomplete to numeric values, which will convert to px.

Using tokens

After your tokens are defined, you can use them to style components.

const Button = styled('button', {
  backgroundColor: '$blue500',
  borderRadius: '$pill',
  color: '$loContrast',
  fontSize: '$3',
  lineHeight: '1',
  fontWeight: 500,
  height: '$6',
  paddingLeft: '$4',
  paddingRight: '$4',
  border: '0',
});

render(<Button>Button</Button>);

Tokens also work inside the css prop.

const Button = styled('button', {
  backgroundColor: '$blue500',
  borderRadius: '$pill',
  color: '$loContrast',
  lineHeight: '1',
  fontWeight: 500,
  border: '0',
});

render(
  <Button
    css={{
      fontSize: '$4',
      height: '$7',
      paddingLeft: '$5',
      paddingRight: '$5',
    }}
  >
    Button
  </Button>
);

Tokens even work with shorthand CSS properties.

const Button = styled('button', {
  backgroundColor: 'white',
  borderRadius: '$pill',
  color: '$blue600',
  fontSize: '$3',
  lineHeight: '1',
  fontWeight: 500,
  height: '$6',
  paddingLeft: '$4',
  paddingRight: '$4',

  // tokens in shorthand properties
  border: '1px solid $blue400',
  boxShadow: '0 5px 15px $blue300',
});

render(<Button>Button</Button>);

Property Mapping

Token types are automatically mapped to CSS Properties for an improved developer experience.

Token
Properties
colors
backgroundColor
color
borderColor
borderRightColor
borderBottomColor
borderLeftColor
caretColor
columnRuleColor
outlineColor
fill
stroke
fonts
fontFamily
fontSizes
fontSize
fontWeights
fontWeight
lineHeights
lineHeight
letterSpacings
letterSpacing
radii
borderRadius
borderTopLeftRadius
borderTopRightRadius
borderBottomRightRadius
borderBottomLeftRadius
sizes
blockSize
minBlockSize
maxBlockSize
inlineSize
minInlineSize
maxInlineSize
width
minWidth
maxWidth
height
minHeight
maxHeight
flexBasis
space
gap
gridGap
columnGap
rowGap
gridRowGap
inset
insetBlock
insetBlockEnd
insetBlockStart
insetInline
insetInlineEnd
insetInlineStart
margin
marginTop
marginRight
marginBottom
marginLeft
marginBlock
marginBlockEnd
marginBlockStart
marginInline
marginInlineEnd
marginInlineStart
padding
paddingTop
paddingRight
paddingBottom
paddingLeft
paddingBlock
paddingBlockEnd
paddingBlockStart
paddingInline
paddingInlineEnd
paddingInlineStart
top
right
bottom
left
zIndices
zIndex