Tokens

Managing design decisions in your app using tokens.

Overview

Design tokens are the platform-agnostic way to manage design decisions in your application or website. It is a collection of attributes that describe any fundamental/atomic visual style. Each attribute is a key-value pair.

Design tokens in Cerberus are largely influenced by the W3C Token Format.

A design token consists of the following properties:

value: The value of the token. This can be any valid CSS value.
description: An optional description of what the token can be used for.

Defining Tokens

Tokens are defined in the under the theme key in your system config.

1
import {
2
  createCerberusConfig,
3
  createCerberusPreset,
4
} from '@cerberus/panda-preset'
5

6
export default createCerberusConfig({
7
  presets: [createCerberusPreset()],
8

9
  include: ['./app/**/*.{ts,tsx}'],
10
  exclude: [],
11

12
  theme: {
13
    tokens: {
14
      colors: {
15
        primary: { value: "#0FEE0F" },
16
        secondary: { value: "#EE0F0F" },
17
      },
18
      fonts: {
19
        body: { value: "system-ui, sans-serif" },
20
      },
21
    },
22
  },
23
})

Using Tokens

After defining tokens, we recommend using the Panda CLI to generate theme typings for your tokens.

1
npm panda codegen

This will provide autocompletion for your tokens in your editor.

1
<Box color="primary" fontFamily="body">
2
  Hello World
3
</Box>

Token reference syntax

Cerberus enables you to reference design tokens within composite values for CSS properties like border, padding, and box-shadow. This is achieved through the token reference syntax: {path.to.token}.

Here’s an example where token reference syntax is applied to both the border and p (padding) props:

1
<Box
2
  border="1px solid {colors.red.300}"
3
  p="{spacing.4} {spacing.6} {spacing.8} {spacing.10}"
4
  boxShadow="{spacing.4} {spacing.2} {spacing.2} {colors.red.300}"
5
/>

Token Nesting

Tokens can be nested to create a hierarchy of tokens. This is useful when you want to group related tokens together.

1
export default createCerberusConfig({
2
  presets: [createCerberusPreset()],
3

4
  include: ['./app/**/*.{ts,tsx}'],
5
  exclude: [],
6

7
  theme: {
8
    tokens: {
9
      colors: {
10
        red: {
11
          DEFAULT: { value: "#EE0F0F" },
12
          100: { value: "#EE0F0F" },
13
        },
14
      },
15
      fonts: {
16
        body: { value: "system-ui, sans-serif" },
17
      },
18
    },
19
  },
20
})

1
<Box
2
  // 👇🏻 This will use the `DEFAULT` value
3
  bg="red"
4
  color="red.100"
5
>
6
  Hello World
7
</Box>

Token Types

Colors

Colors have meaning and support the purpose of the content, communicating things like hierarchy of information, and states. It is mostly defined as a string value or reference to other tokens.

1
import { defineTokens } from "@pandacss/dev"
2

3
export export const tokens = defineTokens({
4
  colors: {
5
    red: {
6
      100: { value: "#fff1f0" },
7
    },
8
  },
9
})

Gradients

Gradient tokens represent a smooth transition between two or more colors. Its value can be defined as a string or a composite value.

1
import { defineTokens } from "@pandacss/dev"
2

3
export export const tokens = defineTokens({
4
  gradients: {
5
    // string value
6
    simple: { value: "linear-gradient(to right, red, blue)" },
7

8
    // composite value
9
    primary: {
10
      value: { type: "linear", placement: "to right", stops: ["red", "blue"] },
11
    },
12
  },
13
})

Sizes

Size tokens represent the width and height of an element. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export export const tokens = defineTokens({
4
  sizes: {
5
    sm: { value: "12px" },
6
  },
7
})

Size tokens are typically used in width, height, minWidth, maxWidth, minHeight, maxHeight properties.

Spacing

Spacing tokens represent the margin and padding of an element. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export export const tokens = defineTokens({
4
  spacing: {
5
    gutter: { value: "12px" },
6
  },
7
})

Spacing tokens are typically used in margin, padding, gap, and {top,right,bottom,left} properties.

Fonts

Font tokens represent the font family of a text element. Its value is defined as a string or an array of strings.

1
import { defineTokens } from "@pandacss/dev"
2

3
export export const tokens = defineTokens({
4
  fonts: {
5
    body: { value: "Inter, sans-serif" },
6
    heading: { value: ["Roboto Mono", "sans-serif"] },
7
  },
8
})

Font tokens are typically used in font-family property.

Font Sizes

Font size tokens represent the size of a text element. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export export const tokens = defineTokens({
4
  fontSizes: {
5
    sm: { value: "12px" },
6
  },
7
})

Font size tokens are typically used in font-size property.

Font Weights

Font weight tokens represent the weight of a text element. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  fontWeights: {
5
    bold: { value: "700" },
6
  },
7
})

Font weight tokens are typically used in font-weight property.

Letter Spacings

Letter spacing tokens represent the spacing between letters in a text element. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  letterSpacings: {
5
    wide: { value: "0.1em" },
6
  },
7
})

Letter spacing tokens are typically used in letter-spacing property.

Line Heights

Line height tokens represent the height of a line of text. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  lineHeights: {
5
    normal: { value: "1.5" },
6
  },
7
})

Line height tokens are typically used in line-height property.

Radii

Radii tokens represent the radius of a border. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  radii: {
5
    sm: { value: "4px" },
6
  },
7
})

Radii tokens are typically used in border-radius property.

Borders

A border is a line surrounding a UI element. You can define them as string values or as a composite value

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  borders: {
5
    // string value
6
    subtle: { value: "1px solid red" },
7
    // string value with reference to color token
8
    danger: { value: "1px solid {colors.red.400}" },
9
    // composite value
10
    accent: { value: { width: "1px", color: "red", style: "solid" } },
11
  },
12
})

Border tokens are typically used in border, border-top, border-right, border-bottom, border-left, outline properties.

Border Widths

Border width tokens represent the width of a border. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  borderWidths: {
5
    thin: { value: "1px" },
6
    thick: { value: "2px" },
7
    medium: { value: "1.5px" },
8
  },
9
})

Shadows

Shadow tokens represent the shadow of an element. Its value is defined as single or multiple values containing a string or a composite value.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  shadows: {
5
    // string value
6
    subtle: { value: "0 1px 2px 0 rgba(0, 0, 0, 0.05)" },
7
    // composite value
8
    accent: {
9
      value: {
10
        offsetX: 0,
11
        offsetY: 4,
12
        blur: 4,
13
        spread: 0,
14
        color: "rgba(0, 0, 0, 0.1)",
15
      },
16
    },
17
    // multiple string values
18
    realistic: {
19
      value: [
20
        "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
21
        "0 1px 4px 0 rgba(0, 0, 0, 0.1)",
22
      ],
23
    },
24
  },
25
})

Shadow tokens are typically used in box-shadow property.

Easings

Easing tokens represent the easing function of an animation or transition. Its value is defined as a string or an array of values representing the cubic bezier.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  easings: {
5
    // string value
6
    easeIn: { value: "cubic-bezier(0.4, 0, 0.2, 1)" },
7
    // array value
8
    easeOut: { value: [0.4, 0, 0.2, 1] },
9
  },
10
})

Ease tokens are typically used in transition-timing-function property.

Opacity

Opacity tokens help you set the opacity of an element.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  opacity: {
5
    50: { value: 0.5 },
6
  },
7
})

Opacity tokens are typically used in opacity property.

Z-Index

This token type represents the depth of an element's position on the z-axis.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  zIndex: {
5
    modal: { value: 1000 },
6
  },
7
})

Z-index tokens are typically used in z-index property.

Assets

Asset tokens represent a url or svg string. Its value is defined as a string or a composite value.

1
type CompositeAsset = { type: "url" | "svg"; value: string }
2
type Asset = string | CompositeAsset

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  tokens: {
5
    assets: {
6
      logo: {
7
        value: { type: "url", value: "/static/logo.png" },
8
      },
9
      checkmark: {
10
        value: { type: "svg", value: "<svg>...</svg>" },
11
      },
12
    },
13
  },
14
})

Asset tokens are typically used in background-image property.

Durations

Duration tokens represent the length of time in milliseconds an animation or animation cycle takes to complete. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  durations: {
5
    fast: { value: "100ms" },
6
  },
7
})

Duration tokens are typically used in transition-duration and animation-duration properties.

Animations

Animation tokens represent a keyframe animation. Its value is defined as a string value.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  animations: {
5
    spin: {
6
      value: "spin 1s linear infinite",
7
    },
8
  },
9
})

Animation tokens are typically used in animation property.

Aspect Ratios

Aspect ratio tokens represent the aspect ratio of an element. Its value is defined as a string.

1
import { defineTokens } from "@pandacss/dev"
2

3
export const tokens = defineTokens({
4
  aspectRatios: {
5
    "1:1": { value: "1 / 1" },
6
    "16:9": { value: "16 / 9" },
7
  },
8
})

On this page

Edit this page on Github