Community程式設計與開發github.com

flatpack-ui

建置介面的技能。使用 Flatpack UI(一個 React 元件庫)開發頁面、螢幕、儀表板或原型。當使用者要求使用 Flatpack UI、黑白元件庫或提到 Flatpack 時使用。提供元件清單、匯入路徑、設計語言規則及可複製貼上的範例,讓 AI 代理能產出符合品牌且可運作的 UI,無需自行發明 API。

flatpack-ui 是什麼?

Flatpack UI 是一個基於 React 19 與 Tailwind CSS 4 的元件庫,其互動元件建構在無樣式且無障礙的 Base UI 基本元件之上,視覺層則由單一 CSS 樣式表驅動。設計規則以「方形、黑白、留白」為核心——所有按鈕、輸入框等可點擊的單行元件使用藥丸形圓角(經 `--fp-radius-control` 控制),而卡片、對話框等內容容器則為直角(`--fp-radius-surface` 為 0)。色彩完全由 CSS 變數定義(如 `--fp-ink`、`--fp-bg`、`--fp-accent`),禁止硬編碼色碼、陰影或漸層;預設主題僅有黑、白及墨水色作為強調色,無藍色或青色連結。CSS 變數涵蓋字型大小(12 至 96px)、間距(4 至 128px)與色彩,並可透過 `data-fp-*` 屬性進行密度、字型及主題切換(如 `flatpack`、`catalog`、`sage`)。本技能適用於 Claude Code、Cursor 等 AI 代理工具,提供完整的元件庫(63 個元件)、匯入路徑、複製貼上範例及反模式清單,代理可直接組合元件而無需自行猜測 API 或撰寫自訂樣式。

相容平台~Claude Code~Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/iamwilllee/flatpack/tree/HEAD/skills/flatpack-ui

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

使用 Flatpack UI 建置介面

Flatpack UI 是一個 React 19 + Tailwind CSS 4 元件庫。互動元件建構在 Base UI 基本元件之上(無樣式、無障礙);視覺層由單一樣式表驅動。其設計規則是 方形、黑白、留白。透過組合庫中的元件來建構畫面;當元件存在時,不要自行手刻有樣式的 <div>。

何時使用

  • 使用者要求建置頁面 / 螢幕 / 儀表板 / 原型,並提到 Flatpack UI 或此黑白元件庫。
  • 使用者希望 UI 符合此專案既有的視覺語言。
  • 不要在一般「幫我做個網站」的要求中使用,除非使用者指名此庫或專案已在使用它。

設定(請先執行此步驟)

Flatpack UI 只需要其樣式表與元件原始碼。在目標專案中:

  1. 從庫根目錄複製主題與元件:
    • src/styles/flatpack.css → 目標 src/styles/flatpack.css
    • src/components/ui/*.tsx → 目標 src/components/ui/
    • src/lib/utils.ts → 目標 src/lib/utils.ts
  2. 若缺少則安裝相依套件: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/)。
  3. 在 Tailwind 之後 匯入主題:
    @import "tailwindcss";
    @import "./styles/flatpack.css";
    
  4. 移除任何庫存的 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,而非元件集。

工作流程

  1. 確認目標專案已整合 Flatpack(上方設定);若未整合,則進行整合。
  2. 閱讀 src/site/componentDocs.ts 以了解任何你不確定 props 的元件——它是真相來源。
  3. 從清單中組合畫面。僅使用 Tailwind 進行佈局/間距。
  4. 根據三條規則檢查結果,並執行 npm run check:design。移除你引入的任何硬編碼值、陰影或裝飾性強調色。
  5. 確認建置成功。如果你加入了不在清單中的元件,請明確說明,並將其保持為情境本機,而非加入基礎集。

相關技能