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.