Flatpack UI でビルドする
Flatpack UI は React 19 + Tailwind CSS 4 のコンポーネントライブラリです。インタラクティブなコンポーネントは Base UI プリミティブ(スタイルなし、アクセシブル)上に構築されており、ビジュアルレイヤーは単一のスタイルシートで提供されます。そのデザインルールは 正方形、白黒、余白 です。ライブラリのコンポーネントを組み合わせて画面を構築し、コンポーネントが存在する場合はスタイル付きの <div> を自作しないでください。
使用するタイミング
- ユーザーが Flatpack UI またはこの白黒コンポーネントライブラリに言及し、ページ / 画面 / ダッシュボード / プロトタイプの作成を依頼した場合。
- ユーザーがこのプロジェクトの確立されたビジュアル言語でUIを希望する場合。
- ユーザーがこのライブラリを明示的に指定しない限り、またはプロジェクトがすでに使用していない限り、一般的な「Webサイトを作って」というリクエストには 使用しない でください。
セットアップ(最初に行うこと)
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 から生成)から取得します。インラインスタイルはトークンのみを参照します: フォントサイズは var(--fp-text-*)(12/14/16/20/28/40/64/96)、間隔は var(--fp-space-*)(4 … 128)、カラートークンは --fp-bg、--fp-surface、--fp-line、--fp-line-strong、--fp-muted、--fp-ink、--fp-danger、--fp-success です。npm run check:design は、これ以外のものがあると失敗します。
3つのルール:
- 役割で形を決める: クリック可能な単一行部分(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">(インクのリング)です。 - 白黒: テーマごとに1つのアクセントカラーで、デフォルトテーマではインク(
--fp-accent)です。青いリンクはなし(リンクは下線付きインク)、シアン、グラデーションはなし。赤と緑はステータステキストとアイコンのみに表示され、塗りつぶしには使用しません。 - 余白: セクションをスペースで区切る(ページセクション間は最低96px)。1pxの境界線は1本のみ。カード内に2つ目の枠線付きボックスを含めないでください。フローティングレイヤー(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/<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 /> を1度マウントし、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 ブロックをコピーしてください。
密度、フォント、オプションのウォームグレーはトークンレベルです: 任意の要素に data-fp-density="compact"(または data-fp-font、data-fp-heading、data-fp-gray)を設定するか、プリセットコードを tokens/overrides.json に記述して npm run build:tokens を実行します。テーマ(flatpack、catalog、sage)は、パレット、アクセント、サーフェスの角丸、フォントスタックを1つのユニットとして入れ替えます: 任意の要素に data-fp-theme="sage" を設定します。塗りつぶしと選択状態は --fp-accent / --fp-on-accent を使用し、テキストは --fp-ink を使用します。テーマ外で1回限りの角丸、アクセントカラー、シャドウ、ぼかしを追加しないでください。
コピペパターン
以下は正確なプロパティです。そのまま使用し、プロパティ名を推測しないでください。
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>Primary</Button>
<Button variant="outline" size="sm">Secondary</Button>
<Button size="icon" aria-label="検索"><Search size={16}/></Button>
// バッジ — variant: default | outline | success | danger
<Badge>New</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" /> {/* 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 を設定して切り替えます(サイトは選択を fp-theme として localStorage に保存し、最初の描画前に index.html で設定します):
document.documentElement.setAttribute('data-theme', 'dark') // または 'light'
コンポーネントにテーマ固有のCSSを記述しないでください。外観をグローバルに変更する必要がある場合は、tokens/flatpack.tokens.json を編集し、npm run build:tokens を実行します。
アンチパターン(やってはいけないこと)
- 新しい色付きのプライマリアクション(例:青や緑のCTA)を発明すること。プライマリは黒/ほぼ白のみです。
- フローティングレイヤー、グラデーション、ガラス効果、色付きの塗りつぶし、カード内の2つ目の境界線の外側にシャドウを追加すること。
- 角丸、ピル型ボタン、大文字の等幅セクションラベル。
- JSXで
var(--fp-*)の代わりに16進数の値をハードコードすること。 Button/Card/Inputをスタイル付き<div>として再実装すること — 常にコンポーネントをインポートしてください。- プロパティを推測すること(
<Button color="red">、<Select items={...}>など)。このスキルにある正確なプロパティを使用してください。 - eコマース固有のコンポーネント(価格タグ、商品タイルなど)をベースライブラリに追加すること。シナリオ固有のUIは Blocks に属し、コンポーネントセットには含めません。
ワークフロー
- 対象プロジェクトに Flatpack が組み込まれていることを確認します(上記セットアップ参照)。組み込まれていない場合は、セットアップを行います。
- プロパティが不明なコンポーネントについては、
src/site/componentDocs.tsを読んでください — これが信頼できる情報源です。 - 一覧からコンポーネントを組み合わせて画面を構成します。Tailwind はレイアウトと間隔にのみ使用します。
- 結果を3つのルールに照らして確認し、
npm run check:designを実行します。導入したハードコードされた値、シャドウ、装飾的なアクセントを削除します。 - ビルドが成功することを確認します。一覧にないコンポーネントを追加した場合は、そのことを明示的に述べ、ベースセットに追加するのではなく、そのシナリオに限定したままにします。