web-ui-chakra-ui

Chakra UI v3 Patterns

Quick Guide: Chakra UI v3 is a composable, accessible React component library. Set up with createSystem(defaultConfig) and ChakraProvider. Style via props (bg, p, color), not className. Components are composable by default (Dialog.Root, Dialog.Content). Theme with design tokens and recipes via defineConfig. Dark mode uses semantic tokens (bg.subtle, fg.muted) and _dark condition. Removed framer-motion and @emotion/styled deps from v2 -- uses CSS animations and recipes instead.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST wrap your app with ChakraProvider value={system} where system is created via createSystem(defaultConfig))

(You MUST use composable component patterns (Dialog.Root, Dialog.Content) -- v3 removed closed component APIs)

(You MUST use style props (bg, p, color) or the chakra factory for styling -- not raw className strings)

(You MUST prefer semantic tokens (bg.subtle, fg.muted) or _dark condition for dark mode -- avoid useColorModeValue when tokens suffice)

</critical_requirements>

Auto-detection: Chakra UI, @chakra-ui/react, ChakraProvider, createSystem, defaultConfig, chakra factory, style props, defineRecipe, defineSlotRecipe, colorPalette, semantic tokens, Ark UI

When to use:

• Building React applications with accessible, composable UI components
• Rapid prototyping with style props (inline CSS via props)
• Implementing design token-based theming with dark mode support
• Creating component variants with the recipe system
• Projects that value accessibility and keyboard navigation out of the box

When NOT to use:

• Projects already using another component library
• Projects requiring zero-runtime CSS (Chakra uses Emotion at runtime)
• Projects that need utility-class-first styling integration
• Extremely bundle-size-sensitive applications

Key patterns covered:

• Provider setup with createSystem and ChakraProvider
• Style props for layout, spacing, color, and typography
• Responsive design with object and array syntax
• Theme customization with tokens, semantic tokens, and recipes
• Composable components (Dialog, Menu, Popover, Drawer)
• Form components with Field pattern
• Dark mode via semantic tokens and _dark condition
• chakra factory for custom styled components

<philosophy>

Philosophy

Chakra UI v3 is built on three pillars: Ark UI (headless component logic and accessibility), Panda CSS-inspired APIs (design tokens and recipes, powered by Emotion at runtime), and Park UI (default design system). Components are composable by default -- you compose Dialog.Root > Dialog.Content > Dialog.Body instead of passing everything as props to a single <Dialog>.

Key v3 principles:

1. Composable over configurable -- compound components replace prop-heavy APIs
2. Tokens over hardcoded values -- colors, spacing, radii reference design tokens
3. Recipes over runtime styles -- variant-based styling replaces runtime theme functions
4. Semantic tokens for dark mode -- bg.subtle adapts automatically, no conditional logic
5. CSS animations over JS -- removed framer-motion, uses native CSS for animations

What Chakra UI handles vs what other skills handle:

• Chakra UI: component structure, style props, design tokens, recipes, composition, accessibility
• Your form library: validation schemas, submission logic, form state management
• Your data layer: server state, caching, mutations

</philosophy>

<patterns>

Core Patterns

Pattern 1: Provider Setup

Every Chakra v3 app needs createSystem and ChakraProvider. Add @layer directive for proper CSS ordering.

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

// Basic: use defaults
export const system = createSystem(defaultConfig);

// Custom: extend with your tokens
const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        brand: {
          50: { value: "#ffe5f1" },
          500: { value: "#d53f8c" },
          900: { value: "#521b41" },
        },
      },
    },
  },
});

export const system = createSystem(defaultConfig, config);

// app.tsx
import { ChakraProvider } from "@chakra-ui/react";
import { system } from "./theme";

export function App({ children }: { children: React.ReactNode }) {
  return <ChakraProvider value={system}>{children}</ChakraProvider>;
}

/* Required CSS layer directive */
@layer reset, base, tokens, recipes;

Why good: createSystem merges your config with defaults, tokens become CSS variables, recipes generate atomic classes

See [examples/core.md](examples/core.md) for framework-specific setup (SPA, SSR).

Pattern 2: Style Props

Style props are the primary way to style elements. They map directly to CSS properties with shorthand aliases and token values.

import { Box, Flex, Text } from "@chakra-ui/react";

// Style props with token values
<Box bg="blue.500" color="white" p="4" rounded="md" shadow="lg">
  Styled via props
</Box>

// Shorthand aliases
<Box
  mt="4"       // marginTop
  px="6"       // paddingX (left + right)
  w="full"     // width: 100%
  maxW="md"    // maxWidth
  mx="auto"    // marginX: auto (centering)
/>

// Layout with Flex
<Flex gap="4" align="center" justify="between" wrap="wrap">
  <Text fontSize="lg" fontWeight="bold">Title</Text>
  <Text color="fg.muted">Subtitle</Text>
</Flex>

Why good: co-located styles, type-safe token values, responsive-ready, no separate CSS files

// BAD: using className strings with Chakra components
<Box className="bg-blue-500 p-4 rounded-md">Wrong approach</Box>

Why bad: bypasses token system, no type safety, loses dark mode adaptation

See [examples/core.md](examples/core.md) for complete style prop reference.

Pattern 3: Responsive Design

Use object syntax (recommended) or array syntax for responsive values. Mobile-first with base as default.

// Object syntax (preferred) -- explicit breakpoint names
<Box
  p={{ base: "4", md: "6", lg: "8" }}
  fontSize={{ base: "sm", md: "md", lg: "lg" }}
  display={{ base: "block", md: "flex" }}
/>

// Array syntax -- positional: [base, sm, md, lg, xl, 2xl]
<Box p={["4", "4", "6", "6", "8"]} />

// Skip breakpoints with undefined
<Text fontWeight={["medium", undefined, undefined, "bold"]} />

// Advanced: range targeting
<Text fontWeight={{ mdToXl: "bold" }} />

// Visibility helpers
<Box hideBelow="md">Desktop only</Box>
<Box hideFrom="md">Mobile only</Box>

Why good: mobile-first approach, named breakpoints are self-documenting, range targeting avoids repetition

Pattern 4: Composable Components

v3 uses compound components with dot notation. All complex components follow Root > Trigger > Content > ... pattern.

import { Dialog, Button } from "@chakra-ui/react";

// Composable dialog
function ConfirmDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <Button>Open</Button>
      </Dialog.Trigger>
      <Dialog.Backdrop />
      <Dialog.Content>
        <Dialog.Header>Confirm Action</Dialog.Header>
        <Dialog.Body>Are you sure?</Dialog.Body>
        <Dialog.Footer>
          <Dialog.CloseTrigger asChild>
            <Button variant="outline">Cancel</Button>
          </Dialog.CloseTrigger>
          <Button colorPalette="red">Confirm</Button>
        </Dialog.Footer>
      </Dialog.Content>
    </Dialog.Root>
  );
}

// BAD: v2-style closed component API (removed in v3)
<Modal isOpen={isOpen} onClose={onClose}>
  <ModalOverlay />
  <ModalContent>
    <ModalHeader>Title</ModalHeader>
    <ModalBody>Content</ModalBody>
  </ModalContent>
</Modal>

Why bad: v2 API removed in v