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.tsThis 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)Semantic Token Nesting
Semantic tokens can be nested to create a hierarchy of tokens. This is useful when you want to group tokens together.
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>