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.
9.4 KiB
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 typegenafter 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:
- Complete theme config —
defineConfigwith all relevant sections - Proper imports —
defineConfig,createSystem,defineRecipe, etc. from@chakra-ui/react - Provider wiring — how to pass
systemtoChakraProviderif needed - Usage examples — show tokens/recipes consumed in a component
- Typegen reminder — note when to run typegen
Brief explanation after the code (2–4 sentences) on key decisions. Skip for trivial requests.