chakra-ui-builder
热门使用 Chakra UI v3 构建响应式且具备无障碍访问（a11y）能力的 UI 组件与布局，在全新或现有项目中安装及配置 Chakra UI，并利用 token、语义化 token、recipe 和 slot recipe 设计可扩展的主题风格。当用户提出以下需求时请调用此 Skill：使用 Chakra UI 构建、创建或生成任意 UI 组件、页面、表单、仪表盘、导航栏、卡片、落地页区域、价格表或布局；向项目中添加 Chakra UI、配置 ChakraProvider、运行 CLI 代码片段（snippets）、配置颜色模式或修复 Provider 包裹问题；或者询问关于主题化（theming）的内容——如定义品牌色、设计 token、语义化 token、深色模式数值、组件 recipe、slot recipe、类型生成（typegen）或导出/解耦默认主题（ejecting default theme）。只要涉及任何 Chakra UI 组件构建、项目配置、主题定制或图表（charts）开发相关的请求，无论表达多么随意（如“帮我加个品牌色”、“做个可复用的卡片样式”、“画个柱状图”、“显示折线图”、“写个登录表单”、“搞个侧边栏”、“把 Chakra 加到我的 App 里”），均需触发此 Skill。
使用 Chakra UI v3 构建响应式且具备无障碍访问（a11y）能力的 UI 组件与布局，在全新或现有项目中安装及配置 Chakra UI，并利用 token、语义化 token、recipe 和 slot recipe 设计可扩展的主题风格。当用户提出以下需求时请调用此 Skill：使用 Chakra UI 构建、创建或生成任意 UI 组件、页面、表单、仪表盘、导航栏、卡片、落地页区域、价格表或布局；向项目中添加 Chakra UI、配置 ChakraProvider、运行 CLI 代码片段（snippets）、配置颜色模式或修复 Provider 包裹问题；或者询问关于主题化（theming）的内容——如定义品牌色、设计 token、语义化 token、深色模式数值、组件 recipe、slot recipe、类型生成（typegen）或导出/解耦默认主题（ejecting default theme）。只要涉及任何 Chakra UI 组件构建、项目配置、主题定制或图表（charts）开发相关的请求，无论表达多么随意（如“帮我加个品牌色”、“做个可复用的卡片样式”、“画个柱状图”、“显示折线图”、“写个登录表单”、“搞个侧边栏”、“把 Chakra 加到我的 App 里”），均需触发此 Skill。
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
- 包管理器（通过 lock 文件判断：
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 注入颜色模式类名而导致的水合不匹配（hydration 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 步 —— 选择正确的布局原语（Layout Primitives）
优先使用 Chakra 恰当的布局原语，而不是把所有东西都套在 Box 里：
| 需求 | 使用组件 |
|---|---|
| 垂直排列项目 | Stack（默认）或 VStack |
| 水平排列项目 | HStack 或 Flex |
| CSS 网格 | Grid + GridItem |
| 等宽多列网格 | SimpleGrid columns={N} |
| 页面居中容器 | Container maxW="container.lg" |
| 完整的 Flexbox 属性控制 | 带有显式属性控制的 Flex |
| 语义化 section/article | Box as="section" / Box as="article" |
避免深层嵌套。如果没有任何语义化理由却嵌套了三层 Box，请扁平化处理。同级元素之间优先使用 gap 而不是 margin。
第 3 步 —— 使用 Token，而非硬编码数值
Chakra v3 内置了语义化 Token，能够自动适应浅色/深色模式。优先使用它们而非硬编码的色值——这样无需额外处理就能让组件具备主题感知能力。
// 推荐使用语义化 Token
<Box bg="bg.subtle" color="fg.default" borderColor="border.subtle" />
<Text color="fg.muted" />
<Box shadow="md" rounded="lg" />
// 交互式组件使用 colorPalette（而不是 colorScheme）
<Button colorPalette="blue">Submit</Button>
<Badge colorPalette="green">Active</Badge>
仅当某种特定颜色是特意指定且不应随颜色模式切换而改变时，才使用硬编码调色板数值（如 blue.500、gray.100）。
第 4 步 —— 响应式样式
Chakra 使用移动端优先的断点策略。请保持一致地使用数组或对象语法：
// 数组语法: [base, sm, md, lg, xl]
<Box px={[4, 6, 8]} fontSize={["sm", "md", "lg"]} />
// 对象语法: 显式断点
<SimpleGrid columns={{ base: 1, md: 2, lg: 3 }} gap={6} />
<Stack direction={{ base: "column", md: "row" }} gap={4} />
除非明确要求仅针对桌面端，否则每个布局组件都应至少适配 base（移动端）和 md（桌面端）断点。
第 5 步 —— 表单
所有表单字段都应使用 Field.Root——它能正确关联 label、input、error 以及 help text：
<Field.Root invalid={!!error} required>
<Field.Label>Email address</Field.Label>
<Input type="email" placeholder="you@example.com" />
<Field.ErrorText>{error}</Field.ErrorText>
<Field.HelpText>We'll never share your email.</Field.HelpText>
</Field.Root>
对于表单提交状态，请在输入框和按钮上使用 disabled（而不是 isDisabled）。关联字段建议用 Stack gap={4} 进行分组。
第 6 步 —— 无障碍访问（Accessibility / a11y）
Chakra 的内置组件会自动处理大部分无障碍特性——切勿覆盖它们。你唯一需要主动提供的是：
- 仅图标按钮（Icon-only buttons）：始终添加
aria-label<IconButton aria-label="Close dialog" icon={<CloseIcon />} /> - 图片：始终传递有意义的
alt文本（纯装饰性图片可传alt=""） - 表单 Label：使用
Field.Label，或确保htmlFor与 input 的id匹配 - 自定义交互元素：如果在
Box上绑定了onClick，请设置as="button"或使用真实的<button>，以便支持键盘导航 - 语义化标题：使用正确的
h1–h6层级；不要跨级使用 - 色彩对比度：避免在白色背景上使用浅灰色文字；依赖经过对比度测试的语义化 Token
第 7 步 —— Next.js：在何处添加 "use client"
在 Next.js App Router 中，服务端组件（Server Components）是默认设置。仅在确实需要的代码文件中添加 "use client"——不要给整个布局或页面都加上。
当组件具备以下特征时需要加上 "use client"：
- 使用了 React Hooks（
useState、useEffect、useContext等） - 处理浏览器事件（带状态更新的
onClick、表单提交等） - 使用了浏览器特有的 API
// 服务端组件 —— 不需要添加指令
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>
)
}
// 客户端组件 —— 需要添加指令
;("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>
)
}
我们的目标是将交互性尽可能下沉至叶子节点（Leaves）——让组件树尽可能多地保持为服务端组件。
第 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 的每个组件，并提供了在相似替代方案之间做出选择的指引。
输出格式
要求输出：
- 完整、可直接运行的代码 —— 正确的导入路径，不要出现
TODO或...rest of component这类占位符 - 规范的导入语句 —— 先组合导入 Chakra 组件，再进行本地导入
- 拆分组件 —— 如果组件复杂或包含明显可解耦的部分，将其拆分为多个组件/文件
- 响应式样式 —— 布局上至少包含
base和md断点 - 代码后的简短说明 —— 用 2–4 句话解释核心决策（布局思路、无障碍考量、响应式策略）。如果是简单需求可省略说明。
// 良好的导入规范示例
import { Box, Button, Field, Stack, Text } from "@chakra-ui/react"
// 紧接着本地导入
import { SomeLocalComponent } from "./SomeLocalComponent"
何时需要先询问用户
如果需求足够明确且能产出有用的代码，请立即进行构建。出现以下情况时请先向用户询问：
- 数据结构未知且影响整体结构（例如：“做个表格”——有多少列？展示什么数据？）
- 存在明显的...
<!-- truncated for translation batch; full body continues in source -->
