使用 Flatpack UI 构建界面
Flatpack UI 是一个 React 19 + Tailwind CSS 4 组件库。交互式组件构建在 Base UI 原语之上(无样式、可访问);视觉层是一个单一的样式表。其设计规则是方形、黑白、留白。通过组合库中的组件来构建屏幕;当存在可用组件时,不要手动编写带有样式的 <div>。
使用时机
- 用户要求构建页面/屏幕/仪表盘/原型,并提到了 Flatpack 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"; - 移除任何 stock 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),绝不能用于章节标题;没有大写标签。图标为 16px 的 lucide 图标。交互仅改变颜色,不改变位置;没有循环动画。
要在相反主题中渲染一个块(例如,一个墨水色横幅,其主按钮必须保持可见),请添加 className="fp-invert"。
使用 .fp-label 类作为小的灰色说明文字;使用 <Kicker> 在标题上方显示一条纯灰色线条。
组件清单
所有导入来自 @/components/ui/<name>(根据目标项目调整别名)。
| 需求 | 组件 |
|---|---|
| 操作 | 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。绝不要在任何主题之外添加独立的圆角、强调色、阴影或模糊效果。
可复制粘贴的模式
以下为精确的属性。请按原样使用;不要猜测属性名。
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'
// Buttons — variant: default | secondary | outline | ghost | link; size: default | sm | lg | icon
<Button>Primary</Button>
<Button variant="outline" size="sm">Secondary</Button>
<Button size="icon" aria-label="Search"><Search size={16}/></Button>
// Badge — variant: default | outline | success | danger
<Badge>New</Badge><Badge variant="success">In stock</Badge>
// Form
<Label>Name</Label>
<Input placeholder="Type here" />
// Card
<Card>
<CardHeader><CardTitle>Title</CardTitle><CardDescription>Subtitle</CardDescription></CardHeader>
<CardContent>...</CardContent>
<CardFooter><Button size="sm">Action</Button></CardFooter>
</Card>
<Kicker>Section eyebrow</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="Enabled" />
<Checkbox indeterminate label="Partial" />
<Checkbox disabled defaultChecked label="Locked" />
<RadioGroup defaultValue="a" options={[
{ value: 'a', label: 'Option A' },
{ value: 'b', label: 'Option B', disabled: true },
]} />
<Switch defaultChecked label="Notifications" />
<Segmented defaultValue="day" options={[
{ value: 'day', label: 'Day' },
{ value: 'week', label: 'Week' },
]} />
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>Open</DialogTrigger>
<DialogContent>
<DialogHeader><DialogTitle>Title</DialogTitle><DialogDescription>Details</DialogDescription></DialogHeader>
<DialogFooter><DialogClose>Close</DialogClose></DialogFooter>
</DialogContent>
</Dialog>
<Sheet>
<SheetTrigger>Cart (2)</SheetTrigger>
<SheetContent title="Cart">...</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>Home</BreadcrumbLink></BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem><BreadcrumbCurrent>Current</BreadcrumbCurrent></BreadcrumbItem>
</Breadcrumb>
<Pagination total={96} pageSize={10} defaultValue={1} onValueChange={(p) => {}} />
<Alert variant="success" title="Saved">Your changes are live.</Alert>
<Progress value={64} label="Progress" showValue />
<Steps current={1} steps={[{ title: 'Start' }, { title: 'Configure' }, { title: 'Done' }]} />
<Empty title="Nothing here" action={<Button size="sm">Create</Button>} />
<Statistic label="Orders" value="1,472" trend={{ value: 12.4 }} />
<Collapse items={[{ key: 'a', title: 'Question', children: 'Answer' }]} />
<Divider label="or" />
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>Items</TableCaption>
<TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Qty</TableHead></TableRow></TableHeader>
<TableBody><TableRow><TableCell>Widget</TableCell><TableCell>1</TableCell></TableRow></TableBody>
</Table>
<Image ratio="4:3" alt="Preview" src="/x.jpg" /> {/* ratios: 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 的渲染文档中。当你需要上面未显示的属性时,请阅读该文件。
主题
主题默认跟随系统。通过设置 <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>——始终导入组件。 - 猜测属性(例如
<Button color="red">、<Select items={...}>)。请使用本技能中提供的精确属性。 - 将特定于电商的组件(价格标签、产品图块)添加到基础库中。特定场景的 UI 属于 Blocks,而不是组件集。
工作流程
- 确认目标项目已配置 Flatpack(参见上面的设置步骤);如果没有,则进行配置。
- 阅读
src/site/componentDocs.ts以了解你不确定属性的任何组件——它是真实的来源。 - 根据清单组合屏幕。仅使用 Tailwind 进行布局/间距。
- 根据三条规则检查结果,并运行
npm run check:design。移除你引入的任何硬编码值、阴影或装饰性强调色。 - 验证它可以构建。如果你添加了清单中没有的组件,请明确说明,并保持该组件仅在场景本地使用,而不是将其添加到基础组件集中。