Semantic Tokens

Leveraging semantic tokens for design decisions in your app.

Overview

Semantic tokens are tokens that are designed to be used in a specific context. A semantic token consists of the following properties:

value: The value of the token or a reference to an existing token.
description: An optional description of what the token can be used for.

Defining Semantic Tokens

In most cases, the value of a semantic token should reference to an existing (primitive) token.

To reference a value in a semantic token, use the token reference {} syntax.

import {
  createCerberusConfig,
  createCerberusPreset,
} from '@cerberus/panda-preset'

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

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

  theme: {
    tokens: {
      colors: {
        red: { value: "#EE0F0F" },
      },
    },
    semanticTokens: {
      colors: {
        invalid: { value: "{colors.red}" },
      },
    },
  },
})

Using Semantic Tokens

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

npm panda codegen

This will provide autocompletion for your tokens in your editor.

<Box color="invalid">Hello World</Box>

Conditional Token

Semantic tokens can also be changed based on the conditions like light and dark modes.

For example, if you want a color to change automatically based on light or dark mode.

import {
  createCerberusConfig,
  createCerberusPreset,
} from '@cerberus/panda-preset'

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

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

  theme: {
    tokens: {
      danger: {
          red: { value: "red.500" },
          darkRed: { value: "red.600" },
          green: { value: "green.500" },
          darkGreen: { value: "green.600" },
        },
    },
    semanticTokens: {
      colors: {
        danger: {
          value: { base: "{colors.red}", _dark: "{colors.darkRed}" },
        },
        success: {
          value: { base: "{colors.green}",  _dark: "{colors.darkGreen}" },
        },
      },
    },
  },
})

The conditions used in semantic tokens must be an at-rule or parent selector condition.

Semantic Token Nesting

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

Use the DEFAULT key to define the default value of a nested token.

import {
  createCerberusConfig,
  createCerberusPreset,
} from '@cerberus/panda-preset'

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

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

  theme: {
    semanticTokens: {
      colors: {
        bg: {
          DEFAULT: { value: "{colors.gray.100}" },
          primary: { value: "{colors.teal.100}" },
          secondary: { value: "{colors.gray.100}" },
        },
      },
    },
  },
})

This allows the use of the bg token in the following ways:

<Box bg="bg">
  <Box bg="bg.primary">Hello World</Box>
  <Box bg="bg.secondary">Hello World</Box>
</Box>

On this page

Edit this page on Github