Community编程与开发github.com

Flatpack UI 界面开发工具

使用 Flatpack UI(一个基于 React 的组件库)构建界面。设计规则由角色决定(药丸形控件、方形表面)、黑白配色、大量留白。当用户要求使用 Flatpack UI 构建页面、屏幕、仪表盘、原型或用户界面时使用。提供组件清单、导入路径、设计语言规则和可直接复用的代码模式,让 AI 代理能够生成风格统一、功能正常且无需自行发明 API 的界面。

Flatpack UI 界面开发工具 是什么?

Flatpack UI 是一个 React 19 + Tailwind CSS 4 组件库,它提供了一套严格但清晰的视觉规则:方形、黑白、留白。该技能的核心优势在于,它为用户(或 AI 代理)提供了一个完整的组件清单(63个组件)、精确的导入路径、以及可直接复制粘贴的 TypeScript 代码片段。代理被要求遵循三条规则:形状由角色决定(交互控件用圆角药丸形,内容表面用方形)、过滤与搜索使用特定模式(如 ChipGroup 和带搜索图标的 Input)、以及在默认主题下仅使用黑色和白色作为强调色。该技能还强调了一个原则:所有视觉决策都必须来自 CSS 变量(如 `--fp-ink`、`--fp-space-*`),禁止硬编码颜色、尺寸或阴影。它适用于任何提及 Flatpack UI 或该黑白组件库的项目,并提供了一个清晰的设置流程:复制样式表和组件源代码、安装依赖、导入主题,然后直接开始组合组件。代理可以通过阅读 `src/site/componentDocs.ts` 文件获取任何组件更详细的 API 信息,并在完成构建后运行 `npm run check:design` 进行设计规则检查。

兼容平台~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 或这个黑白组件库。
  • 用户希望使用该项目已建立的视觉语言来构建界面。
  • 对于泛泛的“给我做一个网站”请求,除非用户明确命名了这个库或者项目已经使用了它,否则不要使用。

设置(请先执行此步骤)

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. 移除任何 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,而不是组件集。

工作流程

  1. 确认目标项目已配置 Flatpack(参见上面的设置步骤);如果没有,则进行配置。
  2. 阅读 src/site/componentDocs.ts 以了解你不确定属性的任何组件——它是真实的来源。
  3. 根据清单组合屏幕。仅使用 Tailwind 进行布局/间距。
  4. 根据三条规则检查结果,并运行 npm run check:design。移除你引入的任何硬编码值、阴影或装饰性强调色。
  5. 验证它可以构建。如果你添加了清单中没有的组件,请明确说明,并保持该组件仅在场景本地使用,而不是将其添加到基础组件集中。

相关技能