Files
AndreaSlopFotografie/web/.agents/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

332 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`:
```ts
// 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`:
```tsx
// 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.
```ts
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.
```ts
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.
```ts
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:
```ts
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.
```ts
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`:
```tsx
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.
```bash
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:
```bash
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.