Communityコーディング&開発github.com

Flatpack UI ビルドスキル

Flatpack UI(React コンポーネントライブラリ)を使って画面やUIを構築するためのコーディングスキルです。デザインルールは「役割で形を決める(ピル型コントロール、正方形サーフェス)、白黒、余白」です。ユーザーがFlatpack UIや白黒コンポーネントライブラリを使ってページ、画面、ダッシュボード、プロトタイプの作成を依頼した場合に使用します。

Flatpack UI ビルドスキル とは?

このスキルは、React 19 と Tailwind CSS 4 をベースにした Flatpack UI コンポーネントライブラリを使用して、一貫性のあるブランドUIを構築するためのエージェント向けガイドです。Flatpack UI のデザインルールは「役割で形を決める」「白黒」「余白」の3つで、すべてのビジュアルはCSS変数(`--fp-*`)で制御され、ハードコードされた色やサイズは禁止されています。コンポーネント一覧、インポートパス、コピペパターン、セットアップ手順が詳細に記載されており、エージェントがAPIを独自に発明することなく、ブランドに沿ったUIを生成できます。このスキルは、Claude CodeやCursor、CodexなどのAIエージェントが、Flatpack UI を使用した画面構築を求められた際に、正確なコンポーネントとプロパティを使用して実装するために利用します。

対応~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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Flatpack UI でビルドする

Flatpack UI は React 19 + Tailwind CSS 4 のコンポーネントライブラリです。インタラクティブなコンポーネントは Base UI プリミティブ(スタイルなし、アクセシブル)上に構築されており、ビジュアルレイヤーは単一のスタイルシートで提供されます。そのデザインルールは 正方形、白黒、余白 です。ライブラリのコンポーネントを組み合わせて画面を構築し、コンポーネントが存在する場合はスタイル付きの <div> を自作しないでください。

使用するタイミング

  • ユーザーが Flatpack UI またはこの白黒コンポーネントライブラリに言及し、ページ / 画面 / ダッシュボード / プロトタイプの作成を依頼した場合。
  • ユーザーがこのプロジェクトの確立されたビジュアル言語でUIを希望する場合。
  • ユーザーがこのライブラリを明示的に指定しない限り、またはプロジェクトがすでに使用していない限り、一般的な「Webサイトを作って」というリクエストには 使用しない でください。

セットアップ(最初に行うこと)

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 から生成)から取得します。インラインスタイルはトークンのみを参照します: フォントサイズは 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 に属し、コンポーネントセットには含めません。

ワークフロー

  1. 対象プロジェクトに Flatpack が組み込まれていることを確認します(上記セットアップ参照)。組み込まれていない場合は、セットアップを行います。
  2. プロパティが不明なコンポーネントについては、src/site/componentDocs.ts を読んでください — これが信頼できる情報源です。
  3. 一覧からコンポーネントを組み合わせて画面を構成します。Tailwind はレイアウトと間隔にのみ使用します。
  4. 結果を3つのルールに照らして確認し、npm run check:design を実行します。導入したハードコードされた値、シャドウ、装飾的なアクセントを削除します。
  5. ビルドが成功することを確認します。一覧にないコンポーネントを追加した場合は、そのことを明示的に述べ、ベースセットに追加するのではなく、そのシナリオに限定したままにします。

関連スキル