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 codegenpnpm panda codegendeno panda npm:codegenbun panda codegenThis 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
DEFAULTkey 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>