# 核心包
npm install @chakra-ui/react @emotion/react
 
# Chakra UI v3 使用 Panda CSS，还需要安装 Panda CSS
npm install @chakra-ui/react @ark-ui/react
 
# 使用 pnpm
pnpm add @chakra-ui/react @ark-ui/react
 
# 可选：图标
npm install @chakra-ui/icons
 
# 注意：v3 不再需要 @emotion/react 和 @emotion/styled

// src/main.tsx
import { ChakraProvider, defaultSystem } from '@chakra-ui/react';
import ReactDOM from 'react-dom/client';
import App from './App';
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <ChakraProvider value={defaultSystem}>
    <App />
  </ChakraProvider>
);

// 自定义主题系统
import { createSystem, defaultConfig, defineConfig } from '@chakra-ui/react';
 
const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        brand: {
          50: { value: '#e6f2ff' },
          500: { value: '#0066cc' },
          900: { value: '#001a33' },
        },
      },
      fonts: {
        heading: { value: '"Inter", sans-serif' },
        body: { value: '"Inter", sans-serif' },
      },
    },
  },
});
 
export const system = createSystem(defaultConfig, config);

import { Box, Button, Heading, Stack, Text } from '@chakra-ui/react';
 
function App() {
  return (
    <Box p={8}>
      <Stack gap={4}>
        <Heading size="lg">欢迎使用 Chakra UI</Heading>
        <Text color="fg.muted">
          简洁、模块化、可访问的 React 组件库
        </Text>
        <Button colorPalette="blue" size="md">
          开始使用
        </Button>
      </Stack>
    </Box>
  );
}
 
export default App;

// v3 组合式 API
import { Accordion } from '@chakra-ui/react';
 
<Accordion.Root defaultValue={['section-1']}>
  <Accordion.Item value="section-1">
    <Accordion.ItemTrigger>第一部分</Accordion.ItemTrigger>
    <Accordion.ItemContent>
      <Accordion.ItemBody>
        这是第一部分内容
      </Accordion.ItemBody>
    </Accordion.ItemContent>
  </Accordion.Item>
  <Accordion.Item value="section-2">
    <Accordion.ItemTrigger>第二部分</Accordion.ItemTrigger>
    <Accordion.ItemContent>
      <Accordion.ItemBody>
        这是第二部分内容
      </Accordion.ItemBody>
    </Accordion.ItemContent>
  </Accordion.Item>
</Accordion.Root>

import { Box, Stack } from '@chakra-ui/react';
 
// 使用样式属性
<Box
  p={4}
  bg="bg.surface"
  borderRadius="lg"
  borderWidth="1px"
  borderColor="border.subtle"
>
  卡片内容
</Box>
 
// 使用 css prop 处理复杂样式
<Box
  css={{
    '&:hover': {
      transform: 'translateY(-2px)',
      boxShadow: 'lg',
    },
  }}
>
  悬停动画效果
</Box>
 
// 响应式样式
<Stack direction={{ base: 'column', md: 'row' }} gap={4}>
  <Box flex={1}>左侧</Box>
  <Box flex={1}>右侧</Box>
</Stack>

// Panda CSS 配置
import { defineConfig } from '@chakra-ui/react';
 
export default defineConfig({
  theme: {
    tokens: {
      // 颜色令牌
      colors: {
        primary: {
          50: { value: '#eff6ff' },
          100: { value: '#dbeafe' },
          500: { value: '#3b82f6' },
          900: { value: '#1e3a5f' },
        },
      },
      // 间距令牌
      spacing: {
        xs: { value: '0.25rem' },
        sm: { value: '0.5rem' },
        md: { value: '1rem' },
        lg: { value: '1.5rem' },
      },
      // 语义令牌
      semanticTokens: {
        colors: {
          'text.primary': { value: '{colors.gray.900}' },
          'text.muted': { value: '{colors.gray.500}' },
          'bg.surface': { value: '{colors.white}' },
        },
      },
    },
  },
});

# 创建新项目
npm create vite@latest my-chakra-app -- --template react-ts
cd my-chakra-app
 
# 安装 Chakra UI v3
npm install @chakra-ui/react @ark-ui/react
 
# 安装 Panda CSS（样式引擎）
npm install -D @pandacss/dev
npx panda init
 
# 开发
npm run dev
 
# 构建（Panda CSS 在构建时生成 CSS）
npm run build

// panda.config.ts
import { defineConfig } from '@pandacss/dev';
 
export default defineConfig({
  preflight: true,
  include: ['./src/**/*.{ts,tsx}'],
  exclude: [],
  theme: {
    extend: {
      tokens: {
        colors: {
          brand: {
            50: { value: '#e6f2ff' },
            500: { value: '#0066cc' },
          },
        },
      },
    },
  },
  outdir: 'styled-system',
});

# 使用 Chakra CLI 添加组件代码片段
npx @chakra-ui/cli snippet add Dialog
npx @chakra-ui/cli snippet add Accordion
npx @chakra-ui/cli snippet add DataTable

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx panda codegen  # 生成 Panda CSS 类型
      - run: npm run typecheck
      - run: npm run lint
      - run: npm run build

// 1. 使用语义化令牌而非直接值
// ✅
<Box bg="bg.surface" color="text.primary" />
 
// ❌ 避免硬编码值
<Box bg="#ffffff" color="#1a1a1a" />
 
// 2. 利用组合式 API 避免不必要的重渲染
<Dialog.Root open={isOpen} onOpenChange={setIsOpen}>
  {/* 子组件不会被父组件状态变化影响 */}
  <Dialog.Content>
    <Dialog.Header>标题</Dialog.Header>
    <Dialog.Body>内容</Dialog.Body>
  </Dialog.Content>
</Dialog.Root>
 
// 3. 使用 css 的 :where 特性减少样式冲突
// Panda CSS 默认使用 :where 降低特异性

// tokens/colors.ts
export const colors = {
  brand: {
    50: { value: '#e6f2ff' },
    500: { value: '#0066cc' },
    900: { value: '#001a33' },
  },
};
 
// tokens/fonts.ts
export const fonts = {
  heading: { value: '"Inter", sans-serif' },
  body: { value: '"Inter", sans-serif' },
};
 
// panda.config.ts
import { colors } from './tokens/colors';
import { fonts } from './tokens/fonts';
 
export default defineConfig({
  theme: {
    extend: { tokens: { colors, fonts } },
  },
});

// ❌ 错误：使用 v2 风格的 API
<Accordion defaultIndex={[0]} allowMultiple>
  <AccordionItem>
    <AccordionButton>标题</AccordionButton>
    <AccordionPanel>内容</AccordionPanel>
  </AccordionItem>
</Accordion>
 
// ✅ 正确：使用 v3 组合式 API
<Accordion.Root defaultValue={['item-1']}>
  <Accordion.Item value="item-1">
    <Accordion.ItemTrigger>标题</Accordion.ItemTrigger>
    <Accordion.ItemContent>
      <Accordion.ItemBody>内容</Accordion.ItemBody>
    </Accordion.ItemContent>
  </Accordion.Item>
</Accordion.Root>

// ❌ 错误：使用 is 前缀（v2 风格）
<Dialog isOpen={isOpen} onClose={onClose}>
 
// ✅ 正确：v3 语义化命名
<Dialog.Root open={isOpen} onOpenChange={setOpen}>

// 表单模式
import { Field, Input, Button, Stack } from '@chakra-ui/react';
 
function LoginForm() {
  return (
    <form onSubmit={handleSubmit}>
      <Stack gap={4} maxW="400px">
        <Field.Root>
          <Field.Label>邮箱</Field.Label>
          <Input type="email" placeholder="请输入邮箱" />
          <Field.HelperText>我们不会分享你的邮箱</Field.HelperText>
        </Field.Root>
        <Field.Root>
          <Field.Label>密码</Field.Label>
          <Input type="password" placeholder="请输入密码" />
        </Field.Root>
        <Button colorPalette="blue" type="submit" size="lg">
          登录
        </Button>
      </Stack>
    </form>
  );
}