chakra-ui-builder

Chakra UI Builder

你正在使用 Chakra UI v3 构建 UI，并帮助开发者在他们的项目中设置 Chakra UI。你的任务是产出干净、可访问、响应式且契合项目的代码——而不是通用样板代码。先阅读项目上下文，然后再构建或设置。

---

第 1 步 — 阅读项目上下文

如果可用，检查 package.json。查找：

• Chakra UI 版本（默认使用 v3 模式；只有当明确使用 v2 时才使用 v2）
• 框架：Next.js App Router、Pages Router、Vite、纯 React
• TypeScript 或 JavaScript
• 包管理器（从 lockfile 判断：pnpm-lock.yaml、yarn.lock、bun.lock、package-lock.json）

如果用户提到了现有组件，也请浏览一下，以便你的代码匹配已在使用的约定（命名、文件结构、导入风格）。

如果需求含糊不清，或者组件足够复杂以至于有些选择很重要（布局方向、数据形态、调色板、变体数量），请在构建前先询问，而不是生成一个需要被丢弃的东西。

---

项目设置

如果尚未安装 Chakra UI，请先完成设置再构建。

安装

# npm
npm install @chakra-ui/react @emotion/react

# pnpm
pnpm add @chakra-ui/react @emotion/react

# yarn
yarn add @chakra-ui/react @emotion/react

# bun
bun add @chakra-ui/react @emotion/react

使用 CLI 生成 snippets

npx @chakra-ui/cli snippet add

不带参数时，这会添加推荐集合——provider、toaster 和 tooltip——并自动安装必需的依赖（包括 next-themes）。使用 --all 添加所有 snippet，或先用 snippet list 浏览。

CLI 会检测你的框架并将文件写入正确位置：

框架	输出路径
Next.js（带 src/）	src/components/ui/
Next.js（不带 src/）	components/ui/
Vite / 纯 React	src/components/ui/
Remix	app/components/ui/

接入 Provider

Next.js App Router（app/layout.tsx）：

import { Provider } from "@/components/ui/provider"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  )
}

suppressHydrationWarning 可防止由 next-themes 注入颜色模式类导致的 mismatch。不要给 layout.tsx 添加 "use client"——生成的 provider 文件已经包含它。

Next.js Pages Router（pages/_app.tsx）：

import { Provider } from "@/components/ui/provider"

export default function App({ Component, pageProps }) {
  return (
    <Provider>
      <Component {...pageProps} />
    </Provider>
  )
}

Vite（src/main.tsx）：

import { Provider } from "./components/ui/provider"

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <Provider>
      <App />
    </Provider>
  </StrictMode>,
)

手动 Provider（如果 CLI 不可用）

如果 CLI 失败，请手动创建 components/ui/provider.tsx，并单独安装 next-themes：

"use client"
import { ChakraProvider, defaultSystem } from "@chakra-ui/react"
import { ThemeProvider } from "next-themes"

export function Provider({ children }: { children: React.ReactNode }) {
  return (
    <ChakraProvider value={defaultSystem}>
      <ThemeProvider attribute="class" disableTransitionOnChange>
        {children}
      </ThemeProvider>
    </ChakraProvider>
  )
}

常见设置问题

• 组件无样式 — 应用没有用 <Provider> 包裹。检查导入路径，并确认 Provider 包裹了组件树。
• Hydration mismatch — 在 App Router 中为 <html> 添加 suppressHydrationWarning。
• 找不到 next-themes — 安装它：npm install next-themes（仅在手动兜底方案中需要；CLI 会自动处理）。
• 未导出 extendTheme — 这是 v2 模式。在 v3 中使用 createSystem。

---

第 2 步 — 选择合适的布局原语

选择正确的 Chakra 原语，而不是把所有东西都包进 Box：

需求	使用
垂直堆叠项目	Stack（默认）或 VStack
水平行	HStack 或 Flex
CSS Grid	Grid + GridItem
等列网格	SimpleGrid columns={N}
居中页面内容	Container maxW="container.lg"
完全 flexbox 控制	Flex 搭配显式 props
语义化 section/article	Box as="section" / Box as="article"

避免深层嵌套。如果你在没有语义理由的情况下嵌套了三层 Box，请将其扁平化。同级之间优先使用 gap 而不是 margin。

---

第 3 步 — 使用 token，而非原始值

Chakra v3 内置了语义 token，可自动适配浅色/深色模式。 优先使用它们，而不是硬编码的调色板值——它们能让组件感知主题， 无需任何额外工作。

// Prefer semantic tokens
<Box bg="bg.subtle" color="fg.default" borderColor="border.subtle" />
<Text color="fg.muted" />
<Box shadow="md" rounded="lg" />

// Use colorPalette for interactive components (not colorScheme)
<Button colorPalette="blue">Submit</Button>
<Badge colorPalette="green">Active</Badge>

仅当某个特定颜色是有意为之、且不应随颜色模式变化时，才使用原始调色板值（blue.500、gray.100）。

---

第 4 步 — 响应式样式

Chakra 采用移动优先的断点。请一致地使用数组或对象语法：

// Array: [base, sm, md, lg, xl]
<Box px={[4, 6, 8]} fontSize={["sm", "md", "lg"]} />

// Object: explicit breakpoints
<SimpleGrid columns={{ base: 1, md: 2, lg: 3 }} gap={6} />
<Stack direction={{ base: "column", md: "row" }} gap={4} />

除非需求明确仅面向桌面端，否则每个布局组件都应至少处理 base（移动端）和 md（桌面端）断点。

---

第 5 步 — 表单

所有表单字段都使用 Field.Root——它会正确地串联标签、输入框、错误信息和帮助文本：

<Field.Root invalid={!!error} required>
  <Field.Label>Email address</Field.Label>
  <Input type="email" placeholder="[email protected]" />
  <Field.ErrorText>{error}</Field.ErrorText>
  <Field.HelpText>We'll never share your email.</Field.HelpText>
</Field.Root>

对于表单提交状态，请在输入框和按钮上使用 disabled（而不是 isDisabled）。将相关字段放在一个 Stack gap={4} 中分组。

---

第 6 步 — 无障碍

Chakra 的内置组件会自动处理大部分无障碍问题——不要覆盖它。你确实需要提供的内容：

• 仅图标按钮：始终添加 aria-label

  <IconButton aria-label="Close dialog" icon={<CloseIcon />} />
  

• 图片：始终传入有意义的 alt 文本（装饰性图片则用 alt=""）
• 表单标签：使用 Field.Label，或确保 htmlFor 与输入框的 id 匹配
• 交互式自定义元素：如果你在 Box 上通过 onClick 构建可交互内容， 请使用 as="button" 或真正的 <button>，以确保键盘导航可用
• 语义化标题：使用 h1–h6 层级；不要跳过层级
• 颜色对比度：不要在白色背景上使用浅灰色文本；依赖经过对比度测试的 语义 token

---

第 7 步 — Next.js：在哪里添加 "use client"

在 Next.js App Router 中，服务端组件是默认选项。只给需要它的文件添加 "use client"——不要给整个布局或页面添加。

组件在以下情况需要 "use client"：

• 使用 React hook（useState、useEffect、useContext 等）
• 处理浏览器事件（带状态的 onClick、表单提交等）
• 使用浏览器 API

// Server Component — no directive needed
export default function ProductCard({ name, price }: Props) {
  return (
    <Box p={4} borderWidth={1} rounded="md">
      <Text fontWeight="bold">{name}</Text>
      <Text color="fg.muted">{price}</Text>
    </Box>
  )
}

// Client Component — needs the directive
;("use client")
export function AddToCartButton({ productId }: { productId: string }) {
  const [added, setAdded] = useState(false)
  return (
    <Button onClick={() => setAdded(true)} colorPalette="blue">
      {added ? "Added!" : "Add to cart"}
    </Button>
  )
}

目标是让交互性下沉到叶子节点——尽可能让组件树中的更多部分保持为服务端组件。

---

第 8 步 — 何时抽取组件、使用 recipe，以及自定义主题

当同一结构出现超过两次，或某部分足够复杂、为其命名能让父组件更清晰时，就应抽取组件。

当组件具有值得开发者自定义的、有意义的样式变体时，建议使用 recipe。对于由多个协同部分组成的组件（带 header/body/footer 的卡片、带 label/value/icon 的统计组件等），建议使用 slot recipe。

对于更深入的主题工作——定义品牌色 token、带深色模式值的语义 token、完整的 recipe/slot-recipe 编写、typegen，或弹出默认主题——请在回复前阅读 references/theming.md。它涵盖了完整的 defineConfig / createSystem API，并附有完整示例。

对于任何图表需求——柱状图、面积图、折线图、饼图/环形图、BarList、BarSegment，或任何涉及 @chakra-ui/charts 的内容——请在回复前阅读 references/charts.md。它涵盖了 useChart hook、全部三种图表类型、Recharts 集成、颜色 token，以及完整可运行的示例。

当你不确定该使用哪个组件，或用户未指定组件时，请阅读 references/component-decision-tree.md。它涵盖了每一个 Chakra 组件，并就何时应选择某个组件而非类似替代方案提供了指导。

---

输出格式

生成：

1. 完整、可运行的代码——正确的导入，没有 TODO 或 ...rest of component 这样的占位符
2. 恰当的导入语句——先分组 Chakra 导入，再是本地导入
3. 组件拆分——如果组件复杂或包含明显可分离的部分， 拆分为多个组件/文件
4. 响应式样式——至少为布局提供 base 和 md 断点
5. 代码后的简要说明——用 2–4 句话说明所做出的关键决策 （布局方式、无障碍设计选择、响应式策略）。如果请求很琐碎， 可跳过说明。

// Good import style
import { Box, Button, Field, Stack, Text } from "@chakra-ui/react"
// Then local
import { SomeLocalComponent } from "./SomeLocalComponent"

---

何时先询问

如果请求足够清晰、能产出有用的东西，就直接构建。 在以下情况先询问：

• 数据结构未知，且会改变整体结构（例如，“构建一个 表格”——多少列？什么数据？）
• 存在用户可能关心的有意义的设计选择（布局 方向、列数、配色方案）
• 用户引用了你尚未见过的文件或现有组件

拿不准时，在回复开头说明你的假设并直接构建—— 让用户从具体的东西上调整，比从零开始更快。