使用 Flatpack UI 建置介面
Flatpack UI 是一個 React 19 + Tailwind CSS 4 元件庫。互動元件建構在 Base UI 基本元件之上(無樣式、無障礙);視覺層由單一樣式表驅動。其設計規則是 方形、黑白、留白。透過組合庫中的元件來建構畫面;當元件存在時,不要自行手刻有樣式的 <div>。
何時使用
- 使用者要求建置頁面 / 螢幕 / 儀表板 / 原型,並提到 Flatpack UI 或此黑白元件庫。
- 使用者希望 UI 符合此專案既有的視覺語言。
- 不要在一般「幫我做個網站」的要求中使用,除非使用者指名此庫或專案已在使用它。
設定(請先執行此步驟)
Flatpack UI 只需要其樣式表與元件原始碼。在目標專案中:
- 從庫根目錄複製主題與元件:
src/styles/flatpack.css→ 目標src/styles/flatpack.csssrc/components/ui/*.tsx→ 目標src/components/ui/src/lib/utils.ts→ 目標src/lib/utils.ts
- 若缺少則安裝相依套件:
react@19 react-dom@19 @base-ui/react clsx tailwind-merge lucide-react。預期已安裝 Tailwind CSS 4 與 TypeScript。互動元件(Button、Checkbox、Switch、RadioGroup、Select、Dialog、Sheet、DropdownMenu、Tabs、Tooltip、Popover、Progress、Avatar、Collapse、Segmented)建構在 Base UI 基本元件之上;純視覺元件則為自包含。發佈使用 shadcn 註冊表格式(registry.json+public/r/)。 - 在 Tailwind 之後 匯入主題:
@import "tailwindcss"; @import "./styles/flatpack.css"; - 移除任何庫存的 shadcn
:root/.dark色彩變數——Flatpack 定義自己的變數。
如果專案已整合此庫,則跳過設定,直接組合元件。
唯一重要的規則
永遠不要硬編碼顏色、尺寸、間距、圓角或陰影。 每個視覺決策都來自 flatpack.css 中的 CSS 變數,這些變數由 tokens/flatpack.tokens.json 產生。行內樣式僅參考 token:字型大小使用 var(--fp-text-*)(12/14/16/20/28/40/64/96),間距使用 var(--fp-space-*)(4 … 128),以及顏色 token --fp-bg、--fp-surface、--fp-line、--fp-line-strong、--fp-muted、--fp-ink、--fp-danger、--fp-success。npm run check:design 會對任何其他值報錯。
三條規則:
- 形狀取決於角色:可點擊的單行元件(Button、ChipGroup、Input、Select、Segmented、Badge、Switch、Tooltip、分頁)使用
--fp-radius-control(預設為藥丸形);承載內容的表面(Card、Image、Dialog、選單、Table、Toast、程式碼、Textarea)使用--fp-radius-surface(0)。沒有中間的半徑。「全方形」預設(data-fp-shape="square"或覆蓋中的 shape: square)會讓控制項也變為 0。 - 篩選與搜尋:獨立的篩選晶片使用
<ChipGroup options={[{ value, label, count? }]} />;搜尋框使用<Input variant="filled" leading={<Search size={16} />} />;次要連結按鈕使用<Button variant="outline">(墨水色邊框)。 - 黑白:每個主題一個強調色,在預設主題中為墨水色(
--fp-accent)。沒有藍色連結(連結為底線墨水色),沒有青色,沒有漸層。紅色與綠色僅出現在狀態文字與圖示中,絕不用作填滿色。 - 留白:用空間分隔區塊(頁面區塊之間至少 96px)。一條 1px 邊框。卡片內絕不包含第二個有邊框的方框。只有浮動層(Dialog、Popover、Select、Dropdown)有陰影。
字型:內文 16px、行高 1.6,標題行高 1.1,字重 400/500/600。等寬字型僅用於數字、ID 與程式碼(.fp-num),絕不用於章節標題;沒有大寫標籤。圖示使用 lucide 的 16px。互動僅改變顏色,不改變位置;沒有循環動畫。
若要在相反主題中渲染區塊(例如墨水色橫幅,其主要按鈕必須保持可見),請加上 className="fp-invert"。
使用 .fp-label 類別作為小型灰色說明文字;使用 <Kicker> 作為標題上方的一般灰色行。
元件清單
所有匯入路徑為 @/components/ui/<名稱>(請根據目標專案調整別名)。
| 需求 | 元件 |
|---|---|
| 動作 | Button、ButtonGroup / ToggleGroup / Toggle (toggle-group)、Toolbar + ToolbarButton/ToolbarToggle/ToolbarGroup/ToolbarSeparator/ToolbarSpacer |
| 容器 | Card + CardHeader/CardTitle/CardDescription/CardContent/CardFooter |
| 標籤 / 狀態 | Badge、StatusDot(8px 方形:default / success / danger / idle)、Kbd / KbdGroup、Kicker(來自 primitives) |
| 文字輸入 | Input、Label、Textarea、NumberInput、Field / Fieldset / FieldControl(標籤 + 幫助 + 錯誤) |
| 選擇 | Select、Combobox(打字預測)、MultiSelect(晶片)、Checkbox、RadioGroup、Switch、Segmented、Slider(單一或範圍) |
| 日期 / 檔案 | Calendar、DatePicker、DateRangePicker、FileInput(僅收集檔案) |
| 覆蓋層 | Dialog、AlertDialog(確認;danger 用於破壞性操作)、Sheet、Popover、HoverCard、DropdownMenu、ContextMenu、Menubar、Tooltip、CommandPalette(⌘K)、Lightbox / LightboxGallery |
| 回饋 | Alert、Toast(掛載 <Toaster /> 一次,呼叫 toast({ title, type }))、Spinner、Skeleton + SkeletonText、Progress、Steps |
| 導覽 | Tabs、Breadcrumb、Pagination、Sidebar + SidebarSection/SidebarItem |
| 資料顯示 | Table(+ 零件)、DescriptionList、Tree、Image、Carousel、Avatar、AvatarGroup、Statistic、Timestamp、Collapse、Empty、CodeBlock / Code |
| 佈局 / 工具 | Divider、Separator(來自 primitives)、ScrollArea、Masonry(瀑布流)、VisuallyHidden、BorderBeam(可選裝飾邊線;預設不使用,因為規則不含循環動畫) |
總計 63 個元件。如果需求不在表格中,請先從這些元件組合,再新增原始碼。刻意不提供的功能:富文本編輯器、Markdown 渲染器、Cascader、Transfer。對於 AI 對話畫面,請複製 src/blocks/BlockScreens.tsx 中的 assistant 區塊。
密度、字型與可選的暖灰色屬於 token 層級:在任何元素上設定 data-fp-density="compact"(或 data-fp-font、data-fp-heading、data-fp-gray),或將預設碼寫入 tokens/overrides.json 並執行 npm run build:tokens。主題(flatpack、catalog、sage)會一併切換色板、強調色、表面半徑與字型堆疊:在任何元素上設定 data-fp-theme="sage"。填滿與選取狀態使用 --fp-accent / --fp-on-accent,文字使用 --fp-ink。切勿在主題之外加入一次性半徑、強調色、陰影或模糊。
複製貼上範例
以下是確切的 props。直接使用,不要猜測 prop 名稱。
import { Button } from '@/components/ui/button'
import { Input, Label } from '@/components/ui/input'
import { Badge } from '@/components/ui/badge'
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card'
import { Kicker, Separator } from '@/components/ui/primitives'
// 按鈕 — variant: default | secondary | outline | ghost | link; size: default | sm | lg | icon
<Button>主要</Button>
<Button variant="outline" size="sm">次要</Button>
<Button size="icon" aria-label="搜尋"><Search size={16}/></Button>
// 徽章 — variant: default | outline | success | danger
<Badge>新增</Badge><Badge variant="success">有庫存</Badge>
// 表單
<Label>名稱</Label>
<Input placeholder="在此輸入" />
// 卡片
<Card>
<CardHeader><CardTitle>標題</CardTitle><CardDescription>副標題</CardDescription></CardHeader>
<CardContent>...</CardContent>
<CardFooter><Button size="sm">動作</Button></CardFooter>
</Card>
<Kicker>區塊眉角</Kicker>
<Separator />
import { Select } from '@/components/ui/select'
import { Checkbox } from '@/components/ui/checkbox'
import { RadioGroup } from '@/components/ui/radio'
import { Switch } from '@/components/ui/switch'
import { Segmented } from '@/components/ui/segmented'
<Select
options={[{ value: 'a', label: 'A' }, { value: 'b', label: 'B' }]}
defaultValue="a"
onValueChange={(v) => {}}
/>
<Checkbox defaultChecked label="啟用" />
<Checkbox indeterminate label="部分" />
<Checkbox disabled defaultChecked label="鎖定" />
<RadioGroup defaultValue="a" options={[
{ value: 'a', label: '選項 A' },
{ value: 'b', label: '選項 B', disabled: true },
]} />
<Switch defaultChecked label="通知" />
<Segmented defaultValue="day" options={[
{ value: 'day', label: '日' },
{ value: 'week', label: '週' },
]} />
import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose } from '@/components/ui/dialog'
import { Sheet, SheetTrigger, SheetContent } from '@/components/ui/sheet'
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs'
import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbCurrent, BreadcrumbSeparator } from '@/components/ui/breadcrumb'
import { Pagination } from '@/components/ui/pagination'
import { Alert } from '@/components/ui/alert'
import { Progress } from '@/components/ui/progress'
import { Steps } from '@/components/ui/steps'
import { Empty } from '@/components/ui/empty'
import { Statistic } from '@/components/ui/statistic'
import { Collapse } from '@/components/ui/collapse'
import { Divider } from '@/components/ui/divider'
<Dialog>
<DialogTrigger>開啟</DialogTrigger>
<DialogContent>
<DialogHeader><DialogTitle>標題</DialogTitle><DialogDescription>詳細資訊</DialogDescription></DialogHeader>
<DialogFooter><DialogClose>關閉</DialogClose></DialogFooter>
</DialogContent>
</Dialog>
<Sheet>
<SheetTrigger>購物車 (2)</SheetTrigger>
<SheetContent title="購物車">...</SheetContent>
</Sheet>
<Tabs defaultValue="a">
<TabsList><TabsTrigger value="a">A</TabsTrigger><TabsTrigger value="b">B</TabsTrigger></TabsList>
<TabsContent value="a">...</TabsContent>
<TabsContent value="b">...</TabsContent>
</Tabs>
<Breadcrumb>
<BreadcrumbItem><BreadcrumbLink>首頁</BreadcrumbLink></BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem><BreadcrumbCurrent>目前</BreadcrumbCurrent></BreadcrumbItem>
</Breadcrumb>
<Pagination total={96} pageSize={10} defaultValue={1} onValueChange={(p) => {}} />
<Alert variant="success" title="已儲存">您的變更已生效。</Alert>
<Progress value={64} label="進度" showValue />
<Steps current={1} steps={[{ title: '開始' }, { title: '設定' }, { title: '完成' }]} />
<Empty title="此處無內容" action={<Button size="sm">建立</Button>} />
<Statistic label="訂單" value="1,472" trend={{ value: 12.4 }} />
<Collapse items={[{ key: 'a', title: '問題', children: '答案' }]} />
<Divider label="或" />
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell, TableCaption } from '@/components/ui/table'
import { Image } from '@/components/ui/image'
import { Avatar } from '@/components/ui/avatar'
import { Skeleton, SkeletonText } from '@/components/ui/skeleton'
<Table>
<TableCaption>項目</TableCaption>
<TableHeader><TableRow><TableHead>名稱</TableHead><TableHead>數量</TableHead></TableRow></TableHeader>
<TableBody><TableRow><TableCell>小工具</TableCell><TableCell>1</TableCell></TableRow></TableBody>
</Table>
<Image ratio="4:3" alt="預覽" src="/x.jpg" /> {/* 比例: square | 4:3 | 16:9 | 3:4 */}
<Avatar size="md" name="Alice" />
<Skeleton circle width={40} height={40} />
<SkeletonText lines={3} />
每個元件的完整 API 表格位於庫中的 src/site/componentDocs.ts 以及渲染的文件 #/docs/components/:id。當你需要上述未顯示的 prop 時,請閱讀該檔案。
主題
主題預設跟隨系統。透過在 <html> 上設定 data-theme 來切換(網站將選擇儲存在 localStorage 中為 fp-theme,並在首次渲染前在 index.html 中設定):
document.documentElement.setAttribute('data-theme', 'dark') // 或 'light'
切勿在元件中撰寫主題特定的 CSS。若需要全域變更外觀,請編輯 tokens/flatpack.tokens.json 並執行 npm run build:tokens。
反模式(請勿執行)
- 發明新的彩色主要動作(例如藍色或綠色的 CTA)。主要動作僅限黑色/近白色。
- 在浮動層之外加入陰影、漸層、玻璃效果、彩色填滿,或卡片內的第二個邊框。
- 圓角、藥丸按鈕、大寫等寬字型章節標籤。
- 在 JSX 中硬編碼十六進位值,而非使用
var(--fp-*)。 - 重新實作
Button/Card/Input為有樣式的<div>——永遠匯入元件。 - 猜測 props(
<Button color="red">、<Select items={...}>)。使用此技能中確切的 props。 - 將電子商務特定元件(價格標籤、產品圖塊)加入基礎庫。情境特定的 UI 屬於 Blocks,而非元件集。
工作流程
- 確認目標專案已整合 Flatpack(上方設定);若未整合,則進行整合。
- 閱讀
src/site/componentDocs.ts以了解任何你不確定 props 的元件——它是真相來源。 - 從清單中組合畫面。僅使用 Tailwind 進行佈局/間距。
- 根據三條規則檢查結果,並執行
npm run check:design。移除你引入的任何硬編碼值、陰影或裝飾性強調色。 - 確認建置成功。如果你加入了不在清單中的元件,請明確說明,並將其保持為情境本機,而非加入基礎集。