Semantic Tokens

Overview

Semantic tokens make your design system smarter and more adaptable. Instead of referencing gray.900 or brand.500, you’ll use meaningful names like fg.default or bg.accent.

Key Takeaways

Semantic tokens describe purpose, not appearance

They represent meaningful roles like bg.surface or fg.accent instead of specific colors, making your design system easier to understand and maintain.

Define them under semanticTokens in your theme

Use the semanticTokens key in your theme configuration to create tokens that map to existing raw color tokens. This way, your system is flexible across light and dark modes.

Reference raw tokens using curly braces {} syntax

Use curly braces to link semantic tokens to raw tokens. This ensures consistency and allows easy updates when base colors change.

const customConfig = defineConfig({
  theme: {
    tokens: {
      colors: {
        brand: {
          500: { value: '#3b82f6' },
          600: { value: '#2563eb' },
        },
      },
    },
    semanticTokens: {
      colors: {
        accent: {
          DEFAULT: { value: '{colors.brand.500}' },
          hover: { value: '{colors.brand.600}' },
        },
      },
    },
  },
})