Files
AndreaSlopFotografie/web/.junie/skills/chakra-ui-builder/references/theming.md
T
Sluijsens e59c3ba4ef Adds Chakra UI CLI, self-hosted fonts, and prettier config
Moves prettier config into web/, adds @chakra-ui/cli for typegen
and the fontsource font packages needed for self-hosted Jost and
Marcellus, and brings in the chakra-ui-* skill docs.
2026-10-02 00:17:39 +02:00

9.4 KiB
Raw Blame History

Chakra UI Theming Reference

Use v3 patterns (defineConfig, createSystem, defineRecipe, defineSlotRecipe) by default. Only use v2 patterns (extendTheme, styleConfig) if the project is explicitly on v2.

Before starting, check package.json for the Chakra UI version and look for an existing theme file (theme.ts, system.ts) to understand what's already defined.

Clarify scope when needed:

  • Full design system — tokens, semantic tokens, and component recipes from scratch
  • Partial update — adding or changing specific tokens or recipes
  • Single recipe — one component's styles with variants
  • Typegen only — running @chakra-ui/cli typegen after custom additions

If the user says "add my brand colors" without specifying the colors, ask first. A partial answer is worse than pausing to clarify.


System setup: defineConfig and createSystem

All theming in v3 starts with createSystem. Use defineConfig to author customizations, then merge with defaultConfig:

// theme.ts
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"

const config = defineConfig({
  theme: {
    tokens: {
      /* ... */
    },
    semanticTokens: {
      /* ... */
    },
    recipes: {
      /* ... */
    },
    slotRecipes: {
      /* ... */
    },
  },
})

export const system = createSystem(defaultConfig, config)

Pass system to ChakraProvider:

// components/ui/provider.tsx
"use client"
import { system } from "@/theme"
import { ChakraProvider } from "@chakra-ui/react"

export function Provider({ children }) {
  return <ChakraProvider value={system}>{children}</ChakraProvider>
}

Tokens

Tokens are the raw, concrete values in your design system — the foundation everything else references.

const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        brand: {
          50: { value: "#eff6ff" },
          100: { value: "#dbeafe" },
          200: { value: "#bfdbfe" },
          500: { value: "#3b82f6" },
          600: { value: "#2563eb" },
          700: { value: "#1d4ed8" },
          900: { value: "#1e3a8a" },
        },
      },
      fonts: {
        heading: { value: "var(--font-geist-sans), sans-serif" },
        body: { value: "var(--font-geist-sans), sans-serif" },
        mono: { value: "var(--font-geist-mono), monospace" },
      },
      fontSizes: {
        xs: { value: "0.75rem" },
        sm: { value: "0.875rem" },
        md: { value: "1rem" },
        lg: { value: "1.125rem" },
        xl: { value: "1.25rem" },
        "2xl": { value: "1.5rem" },
      },
      radii: {
        sm: { value: "0.25rem" },
        md: { value: "0.375rem" },
        lg: { value: "0.5rem" },
        xl: { value: "0.75rem" },
        full: { value: "9999px" },
      },
    },
  },
})

Use scale-based keys for palettes (50, 100, …, 900) and semantic keys for single values (sm, md, lg).


Semantic tokens

Semantic tokens reference base tokens and assign meaning to them. Their key feature: different values per color mode, making dark mode automatic.

const config = defineConfig({
  theme: {
    semanticTokens: {
      colors: {
        "brand.solid": {
          value: { base: "{colors.brand.600}", _dark: "{colors.brand.400}" },
        },
        "brand.muted": {
          value: { base: "{colors.brand.100}", _dark: "{colors.brand.900}" },
        },
        "brand.subtle": {
          value: { base: "{colors.brand.50}", _dark: "{colors.brand.950}" },
        },

        "bg.default": { value: { base: "white", _dark: "{colors.gray.900}" } },
        "bg.subtle": {
          value: { base: "{colors.gray.50}", _dark: "{colors.gray.800}" },
        },
        "bg.muted": {
          value: { base: "{colors.gray.100}", _dark: "{colors.gray.700}" },
        },

        "fg.default": { value: { base: "{colors.gray.900}", _dark: "white" } },
        "fg.muted": {
          value: { base: "{colors.gray.600}", _dark: "{colors.gray.400}" },
        },
        "fg.subtle": {
          value: { base: "{colors.gray.400}", _dark: "{colors.gray.600}" },
        },

        "border.default": {
          value: { base: "{colors.gray.200}", _dark: "{colors.gray.700}" },
        },
        "border.muted": {
          value: { base: "{colors.gray.100}", _dark: "{colors.gray.800}" },
        },
      },
    },
  },
})

Components that use bg="bg.subtle" instead of bg="gray.50" automatically get the correct dark mode value — no conditional logic needed. Build on semantic tokens wherever possible.


Recipes (single-component styles)

Recipes replace styleConfig from v2. Use them when a single component has meaningful style variants that developers will reuse across the project.

import { defineRecipe } from "@chakra-ui/react"

export const badgeRecipe = defineRecipe({
  base: {
    display: "inline-flex",
    alignItems: "center",
    px: 2,
    py: 0.5,
    borderRadius: "full",
    fontSize: "xs",
    fontWeight: "medium",
  },
  variants: {
    variant: {
      solid: { bg: "colorPalette.500", color: "white" },
      subtle: { bg: "colorPalette.100", color: "colorPalette.800" },
      outline: {
        borderWidth: 1,
        borderColor: "colorPalette.500",
        color: "colorPalette.600",
      },
    },
    size: {
      sm: { px: 1.5, py: 0.5, fontSize: "2xs" },
      md: { px: 2, py: 0.5, fontSize: "xs" },
      lg: { px: 3, py: 1, fontSize: "sm" },
    },
  },
  defaultVariants: { variant: "subtle", size: "md" },
})

Register in the theme config:

const config = defineConfig({ theme: { recipes: { badge: badgeRecipe } } })

colorPalette inside a recipe is a placeholder — it resolves to whatever colorPalette prop the consumer passes (colorPalette="blue" → blue.500).


Slot recipes (multi-part components)

Slot recipes replace multiStyleConfig from v2. Use them when a component has multiple coordinated parts that all respond to the same variants.

import { defineSlotRecipe } from "@chakra-ui/react"

export const cardSlotRecipe = defineSlotRecipe({
  slots: ["root", "header", "body", "footer", "title"],
  base: {
    root: { bg: "bg.surface", rounded: "xl", overflow: "hidden", shadow: "sm" },
    header: { px: 6, py: 4, borderBottomWidth: 1, borderColor: "border.muted" },
    body: { px: 6, py: 4 },
    footer: { px: 6, py: 4, borderTopWidth: 1, borderColor: "border.muted" },
    title: { fontSize: "lg", fontWeight: "semibold", color: "fg.default" },
  },
  variants: {
    variant: {
      elevated: { root: { shadow: "md" } },
      outline: {
        root: { shadow: "none", borderWidth: 1, borderColor: "border.default" },
      },
      filled: { root: { bg: "bg.subtle", shadow: "none" } },
    },
    size: {
      sm: {
        root: { rounded: "lg" },
        body: { px: 4, py: 3 },
        header: { px: 4, py: 3 },
      },
      md: {},
      lg: { body: { px: 8, py: 6 }, header: { px: 8, py: 6 } },
    },
  },
  defaultVariants: { variant: "elevated", size: "md" },
})

Register: const config = defineConfig({ theme: { slotRecipes: { card: cardSlotRecipe } } })

Consume with useSlotRecipe:

import { useSlotRecipe } from "@chakra-ui/react"

function Card({ variant = "elevated", size = "md", children }) {
  const recipe = useSlotRecipe({ key: "card" })
  const styles = recipe({ variant, size })
  return <Box css={styles.root}>{children}</Box>
}

Typegen

Run typegen after adding custom tokens, semantic tokens, recipes, or slot recipes. Without it, TypeScript won't know your custom values exist.

npx @chakra-ui/cli typegen ./theme.ts
Flag Effect
--strict Strict literal types for variant and size props (recommended)
--watch Re-runs automatically whenever the theme file changes
--outdir <dir> Custom output directory for generated types
--tsconfig <path> Path to tsconfig when using path aliases

For active development: npx @chakra-ui/cli typegen ./theme.ts --watch

Typegen is required when you've added custom color tokens, semantic tokens, spacing/font/radius tokens, or new recipes or slot recipes.


Ejecting the default theme

For full control over Chakra's built-in tokens, recipes, and styles:

npx @chakra-ui/cli eject

Writes the complete default theme into a theme/ directory (--outdir <dir> to override), including separate files for tokens, semantic tokens, recipes, slot recipes, text styles, layer styles, and animation styles — all as editable defineConfig exports.

Use eject when modifying built-in component recipes or replacing large parts of the default token scale. For smaller customizations (adding brand colors, overriding a few tokens), extending with defineConfig is simpler.


Output format

Produce:

  1. Complete theme config — defineConfig with all relevant sections
  2. Proper imports — defineConfig, createSystem, defineRecipe, etc. from @chakra-ui/react
  3. Provider wiring — how to pass system to ChakraProvider if needed
  4. Usage examples — show tokens/recipes consumed in a component
  5. Typegen reminder — note when to run typegen

Brief explanation after the code (2–4 sentences) on key decisions. Skip for trivial requests.