chakra-ui-builder

Name: chakra-ui-builder
Author: chakra-ui

Chakra UI Builder

您正在使用 Chakra UI v3 建構 UI，並協助開發者在專案中設定 Chakra UI。您的職責是產出乾淨、具備無障礙性且支援響應式的程式碼，並完美契合專案需求，而非產生泛用的範本樣板（boilerplate）。建構或設定前，請先閱讀專案上下文。

步驟 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）

若使用者提及現有元件，也請順道瀏覽一下，確保寫出的程式碼符合專案現有的撰寫慣例（命名、檔案結構、import 風格）。

若需求較為模糊，或元件複雜度較高且細節選擇至為關鍵（例如版面方向、資料結構、色調調色盤、變體數量等），請在開始建構前先提問確認，避免產出不符需求的無用程式碼。

專案設定

若尚未安裝 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 注入色彩模式（color-mode）class 而導致的 Hydration 不一致問題。請不要在 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> 包覆。請檢查 import 路徑並確認 Provider 是否包覆了整個元件樹。
Hydration 不一致 — 在 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	`Grid` + `GridItem`
等寬網格	`SimpleGrid columns={N}`
置中頁面內容	`Container maxW="container.lg"`
完全掌控 Flexbox 設定	搭配明確屬性（props）的 `Flex`
語意化 section/article	`Box as="section"` / `Box as="article"`

避免過深的情節嵌套。若無語意上的理由卻疊了三層 Box，請簡化結構。同層元件之間請優先使用 gap 而非 margin。

步驟 3 — 使用 Token，而非硬編碼數值

Chakra v3 內建了能自動適應淺色/深色模式的語意化 Token（semantic tokens）。相較於寫死的色調數值，請優先使用語意化 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 採用行動優先（mobile-first）的中斷點（breakpoints）。請一致地使用陣列或物件語法：

// 陣列語法：[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）

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 中，預設皆為 Server Components。請僅在必要的檔案中加上 "use client"——切勿直接加在整個 layout 或 page 頁面上。

元件在以下情況需要加上 "use client"：

使用 React hooks（useState、useEffect、useContext 等）
處理瀏覽器事件（包含狀態變更的 onClick、表單送出等）
使用瀏覽器 API

// Server Component — 無需加指示詞
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 — 需要加指示詞
;("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），盡可能保留最多的 Server Components。

步驟 8 — 何時拆分元件、使用 Recipe 以及自訂主題

當相同的結構出現超過兩次，或是某個部分的複雜度高到命名後能提升父元件清晰度時，請將其抽離為獨立元件。

當元件具備開發者會想要自訂的樣式變體（style variants）時，建議採用 recipe。對於包含多個協調子部件的元件（例如包含 header/body/footer 的卡片，或是包含 label/value/icon 的數據統計），則建議使用 slot recipe。

若需要進行更深入的主題化工作——包含定義品牌色彩 Token、帶有深色模式數值的語意化 Token、完整撰寫 recipe/slot-recipe、typegen、或是 eject 預設主題——請在回覆前參閱 references/theming.md。該文件涵蓋了完整的 defineConfig / createSystem API 與完整範例。

凡涉及圖表需求——包含長條圖、面積圖、折線圖、圓餅圖/甜甜圈圖、BarList、BarSegment，或任何使用 @chakra-ui/charts 的內容——請在回覆前參閱 references/charts.md。該文件涵蓋了 useChart hook、三種圖表類型、Recharts 整合、顏色 Token 以及完整的可執行範例。

當您不確定該使用哪個元件，或是使用者未指定特定元件時，請參閱 references/component-decision-tree.md。它涵蓋了每個 Chakra 元件，並針對在類似替代方案中該如何選擇提供了相應指引。

輸出格式

請產出：

完整且可執行的程式碼 — 具備正確的 import 語法，不得有 TODO 或 ...rest of component 等預設占位符
正確的 import 敘述句 — 優先將 Chakra 的 import 歸類在一起，接著才是本機專案的 import
元件拆分 — 若元件較為複雜或包含可明確拆分的部件，請將其分拆至多個元件/檔案中
響應式樣式 — 版面配置至少需要處理 base 與 md 中斷點
程式碼後附帶簡短說明 — 用 2 到 4 句話解釋所做出的核心決策（版面配置處理方式、無障礙設計考量、響應式策略）。若需求非常簡單則可省略說明。

// 良好的 import 風格
import { Box, Button, Field, Stack, Text } from "@chakra-ui/react"
// 接著為本機 import
import { SomeLocalComponent } from "./SomeLocalComponent"