Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsPlaygroundGuidesBlog
Sponsor

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 references to an existing token.

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

theme.ts

import { createSystem, defineConfig } from "@chakra-ui/react"

const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        red: { value: "#EE0F0F" },
      },
    },
    semanticTokens: {
      colors: {
        danger: { value: "{colors.red}" },
      },
    },
  },
})

export default createSystem(config)

Using Semantic Tokens

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

npx @chakra-ui/cli typegen ./src/theme.ts

This will provide autocompletion for your tokens in your editor.

<Box color="danger">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.

theme.ts

import { createSystem, defineConfig } from "@chakra-ui/react"

const config = defineConfig({
  theme: {
    semanticTokens: {
      colors: {
        danger: {
          value: { base: "{colors.red}", _dark: "{colors.darkred}" },
        },
        success: {
          value: { base: "{colors.green}", _dark: "{colors.darkgreen}" },
        },
      },
    },
  },
})

export default createSystem(config)
info
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.

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

theme.ts

import { createSystem, defineConfig } from "@chakra-ui/react"

const config = defineConfig({
  theme: {
    semanticTokens: {
      colors: {
        bg: {
          DEFAULT: { value: "{colors.gray.100}" },
          primary: { value: "{colors.teal.100}" },
          secondary: { value: "{colors.gray.100}" },
        },
      },
    },
  },
})

export default createSystem(config)

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>

Previous

Tokens

Next

Recipes