CommunityCodierung & Entwicklunggithub.com

flatpack-ui

Fertigkeit zum Erstellen von Benutzeroberflächen mit Flatpack UI, einer React-Komponentenbibliothek, deren Designregeln durch Rollen (Pillen-Steuerelemente, quadratische Oberflächen), Schwarz-Weiß und Leerraum geprägt sind.

Was ist flatpack-ui?

Flatpack UI ist eine dedizierte Fertigkeit für KI-Agenten, die die Entwicklung von Marken-konformen, funktionalen Benutzeroberflächen mit einer React 19 + Tailwind CSS 4 Komponentenbibliothek ermöglicht. Es eignet sich für Szenarien, in denen ein Benutzer den Aufbau einer Seite, eines Dashboards oder eines Prototyps anfordert und sich speziell auf die Flatpack- oder Schwarz-Weiß-Komponentenbibliothek bezieht. Die Fertigkeit stellt einen vollständigen Komponentenkatalog, exakte Importpfade, Designsprache-Regeln und Copy-Paste-Muster bereit, sodass der Agent ohne das Erfinden neuer APIs ein konsistentes, produktionsreifes UI erstellt. Sie wird hauptsächlich in KI-Codierungsassistenten wie Claude Code, Cursor und Codex verwendet, um sicherzustellen, dass die generierten Bildschirme den Regeln für form-rolle, Schwarz-Weiß und Leerraum folgen und gleichzeitig unterstützte Muster wie Akkordeons, Dialoge und Datentabellen verwendet werden.

Funktioniert mit~Claude Code~Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/iamwilllee/flatpack/tree/HEAD/skills/flatpack-ui

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Mit Flatpack UI erstellen

Flatpack UI ist eine React 19 + Tailwind CSS 4 Komponentenbibliothek. Interaktive Komponenten basieren auf Base UI Primitiven (unstyled, barrierefrei); die visuelle Ebene ist ein einziges Stylesheet. Die Entwurfsregeln sind quadratisch, schwarz-weiß, Leerraum. Erstellen Sie Bildschirme, indem Sie die Komponenten der Bibliothek zusammensetzen; verwenden Sie keine handgemachten gestylten <div>s, wenn eine Komponente existiert.

Wann verwenden

  • Der Benutzer bittet um die Erstellung einer Seite / eines Bildschirms / eines Dashboards / eines Prototyps und erwähnt Flatpack UI oder diese Schwarz-Weiß-Komponentenbibliothek.
  • Der Benutzer wünscht sich ein UI in der etablierten visuellen Sprache dieses Projekts.
  • Nicht verwenden für eine allgemeine "Erstelle mir eine Website"-Anfrage, es sei denn, der Benutzer nennt diese Bibliothek oder das Projekt verwendet sie bereits.

Einrichtung (zuerst durchführen)

Flatpack UI benötigt nur sein Stylesheet und die Komponentenquellen. In einem Zielprojekt:

  1. Kopieren Sie das Theme und die Komponenten aus dem Bibliotheksstamm:
    • src/styles/flatpack.css → Ziel src/styles/flatpack.css
    • src/components/ui/*.tsx → Ziel src/components/ui/
    • src/lib/utils.ts → Ziel src/lib/utils.ts
  2. Installieren Sie fehlende Abhängigkeiten: react@19 react-dom@19 @base-ui/react clsx tailwind-merge lucide-react. Tailwind CSS 4 und TypeScript werden erwartet. Interaktive Komponenten (Button, Checkbox, Switch, RadioGroup, Select, Dialog, Sheet, DropdownMenu, Tabs, Tooltip, Popover, Progress, Avatar, Collapse, Segmented) basieren auf Base UI Primitiven; rein visuelle Komponenten sind in sich geschlossen. Die Verteilung erfolgt über das shadcn-Registrierungsformat (registry.json + public/r/).
  3. Importieren Sie das Theme nach Tailwind:
    @import "tailwindcss";
    @import "./styles/flatpack.css";
    
  4. Entfernen Sie alle Standard-:root / .dark Farbvariablen von shadcn — Flatpack definiert eigene.

Wenn das Projekt die Bibliothek bereits eingebunden hat, überspringen Sie die Einrichtung und gehen Sie direkt zum Zusammensetzen der Komponenten.

Die eine Regel, die zählt

Härten Sie niemals Farben, Größen, Abstände, Radien oder Schatten fest. Jede visuelle Entscheidung stammt aus einer CSS-Variable in flatpack.css, generiert aus tokens/flatpack.tokens.json. Inline-Stile referenzieren nur Tokens: var(--fp-text-*) für Schriftgrößen (12/14/16/20/28/40/64/96), var(--fp-space-*) für Abstände (4 … 128), und die Farb-Tokens --fp-bg, --fp-surface, --fp-line, --fp-line-strong, --fp-muted, --fp-ink, --fp-danger, --fp-success. npm run check:design schlägt bei allem anderen fehl.

Die drei Regeln:

  • Form nach Rolle: Klickbare einzeilige Teile (Button, ChipGroup, Input, Select, Segmented, Badge, Switch, Tooltip, Paginierung) verwenden --fp-radius-control (standardmäßig eine Pille); Oberflächen, die Inhalt enthalten (Card, Image, Dialog, Menüs, Table, Toast, Code, Textarea) verwenden --fp-radius-surface (0). Keine Zwischenradien. Das "All square"-Preset (data-fp-shape="square" oder shape: square in Overrides) macht auch Steuerelemente auf 0.
  • Filter und Suche: Separate Filter-Chips sind <ChipGroup options={[{ value, label, count? }]} />; ein Suchfeld ist <Input variant="filled" leading={<Search size={16} />} />; ein sekundärer Link-Button ist <Button variant="outline"> (Ink-Ring).
  • Schwarz und Weiß: Ein Akzent pro Theme, und im Standard-Theme ist es Ink (--fp-accent). Keine blauen Links (Links sind unterstrichener Ink), kein Cyan, keine Verläufe. Rot und Grün erscheinen nur in Statustexten und -symbolen, niemals als Füllung.
  • Leerraum: Trennen Sie Abschnitte mit Abstand (mindestens 96px zwischen Seitenabschnitten). Eine 1px-Grenze. Eine Karte enthält niemals eine zweite umrahmte Box. Nur schwebende Ebenen (Dialog, Popover, Select, Dropdown) haben einen Schatten.

Typ: Text 16px bei 1.6, Überschriften 1.1, Gewichte 400/500/600. Monospace nur für Zahlen, IDs und Code (.fp-num), niemals für Abschnittstitel; keine Großbuchstaben-Beschriftungen. Symbole sind Lucide bei 16px. Interaktion ändert nur die Farbe, niemals die Position; keine Schleifenanimation.

Um einen Block im entgegengesetzten Thema darzustellen (z. B. ein Ink-Banner, dessen primärer Button sichtbar bleiben muss), fügen Sie className="fp-invert" hinzu.

Verwenden Sie die Klasse .fp-label für eine kleine graue Beschriftung; verwenden Sie <Kicker> für eine einfache graue Zeile über einer Überschrift.

Komponentenverzeichnis

Alle Importe erfolgen von @/components/ui/<name> (passen Sie den Alias an das Zielprojekt an).

BedarfKomponente
AktionenButton, ButtonGroup / ToggleGroup / Toggle (toggle-group), Toolbar + ToolbarButton/ToolbarToggle/ToolbarGroup/ToolbarSeparator/ToolbarSpacer
ContainerCard + CardHeader/CardTitle/CardDescription/CardContent/CardFooter
Labels / StatusBadge, StatusDot (8px quadratisch: default / success / danger / idle), Kbd / KbdGroup, Kicker (aus primitives)
TexteingabeInput, Label, Textarea, NumberInput, Field / Fieldset / FieldControl (Label + Hilfe + Fehler)
AuswahlSelect, Combobox (Typeahead), MultiSelect (Chips), Checkbox, RadioGroup, Switch, Segmented, Slider (einfach oder Bereich)
Daten / DateienCalendar, DatePicker, DateRangePicker, FileInput (sammelt nur Dateien)
ÜberlagerungenDialog, AlertDialog (bestätigen; danger für destruktiv), Sheet, Popover, HoverCard, DropdownMenu, ContextMenu, Menubar, Tooltip, CommandPalette (⌘K), Lightbox / LightboxGallery
RückmeldungAlert, Toast (mounten Sie <Toaster /> einmal, rufen Sie toast({ title, type }) auf), Spinner, Skeleton + SkeletonText, Progress, Steps
NavigationTabs, Breadcrumb, Pagination, Sidebar + SidebarSection/SidebarItem
DatenanzeigeTable (+ Teile), DescriptionList, Tree, Image, Carousel, Avatar, AvatarGroup, Statistic, Timestamp, Collapse, Empty, CodeBlock / Code
Layout / DienstprogrammDivider, Separator (aus primitives), ScrollArea, Masonry (Wasserfall), VisuallyHidden, BorderBeam (optionale dekorative Randlinie; nicht standardmäßig verwendet, da die Regeln keine Schleifenanimation haben)

Insgesamt 63 Komponenten. Wenn ein Bedarf nicht in der Tabelle enthalten ist, setzen Sie aus diesen Komponenten zusammen, bevor Sie neue Quellen hinzufügen. Nicht bereitgestellt, mit Absicht: Rich-Text-Editor, Markdown-Renderer, Cascader, Transfer. Erstellen Sie für KI-Chat-Bildschirme den assistant-Block in src/blocks/BlockScreens.tsx.

Dichte, Schriftarten und das optionale warme Grau sind auf Token-Ebene: Setzen Sie data-fp-density="compact" (oder data-fp-font, data-fp-heading, data-fp-gray) auf jedes Element, oder schreiben Sie eine Voreinstellung in tokens/overrides.json und führen Sie npm run build:tokens aus. Themes (flatpack, catalog, sage) tauschen Palette, Akzent, Oberflächenradius und Schriftstapel als eine Einheit aus: Setzen Sie data-fp-theme="sage" auf jedes Element. Füll- und Auswahlzustände verwenden --fp-accent / --fp-on-accent, Text verwendet --fp-ink. Fügen Sie niemals einmalige Radien, Akzentfarben, Schatten oder Unschärfen außerhalb eines Themes hinzu.

Copy-Paste-Muster

Dies sind die genauen Props. Verwenden Sie sie wie angegeben; raten Sie nicht die Prop-Namen.

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>Primär</Button>
<Button variant="outline" size="sm">Sekundär</Button>
<Button size="icon" aria-label="Suche"><Search size={16}/></Button>

// Badge — variant: default | outline | success | danger
<Badge>Neu</Badge><Badge variant="success">Auf Lager</Badge>

// Formular
<Label>Name</Label>
<Input placeholder="Hier tippen" />

// Karte
<Card>
  <CardHeader><CardTitle>Titel</CardTitle><CardDescription>Untertitel</CardDescription></CardHeader>
  <CardContent>...</CardContent>
  <CardFooter><Button size="sm">Aktion</Button></CardFooter>
</Card>

<Kicker>Abschnittsüberschrift</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="Aktiviert" />
<Checkbox indeterminate label="Teilweise" />
<Checkbox disabled defaultChecked label="Gesperrt" />

<RadioGroup defaultValue="a" options={[
  { value: 'a', label: 'Option A' },
  { value: 'b', label: 'Option B', disabled: true },
]} />

<Switch defaultChecked label="Benachrichtigungen" />

<Segmented defaultValue="day" options={[
  { value: 'day', label: 'Tag' },
  { value: 'week', label: 'Woche' },
]} />
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>Öffnen</DialogTrigger>
  <DialogContent>
    <DialogHeader><DialogTitle>Titel</DialogTitle><DialogDescription>Details</DialogDescription></DialogHeader>
    <DialogFooter><DialogClose>Schließen</DialogClose></DialogFooter>
  </DialogContent>
</Dialog>

<Sheet>
  <SheetTrigger>Warenkorb (2)</SheetTrigger>
  <SheetContent title="Warenkorb">...</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>Startseite</BreadcrumbLink></BreadcrumbItem>
  <BreadcrumbSeparator />
  <BreadcrumbItem><BreadcrumbCurrent>Aktuell</BreadcrumbCurrent></BreadcrumbItem>
</Breadcrumb>

<Pagination total={96} pageSize={10} defaultValue={1} onValueChange={(p) => {}} />
<Alert variant="success" title="Gespeichert">Ihre Änderungen sind live.</Alert>
<Progress value={64} label="Fortschritt" showValue />
<Steps current={1} steps={[{ title: 'Start' }, { title: 'Konfigurieren' }, { title: 'Fertig' }]} />
<Empty title="Nichts hier" action={<Button size="sm">Erstellen</Button>} />
<Statistic label="Bestellungen" value="1,472" trend={{ value: 12.4 }} />
<Collapse items={[{ key: 'a', title: 'Frage', children: 'Antwort' }]} />
<Divider label="oder" />
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>Artikel</TableCaption>
  <TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Menge</TableHead></TableRow></TableHeader>
  <TableBody><TableRow><TableCell>Widget</TableCell><TableCell>1</TableCell></TableRow></TableBody>
</Table>

<Image ratio="4:3" alt="Vorschau" 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} />

Vollständige API-Tabellen für jede Komponente befinden sich in der src/site/componentDocs.ts der Bibliothek und in den gerenderten Dokumentationen unter #/docs/components/:id. Lesen Sie diese Datei, wenn Sie ein Prop benötigen, das oben nicht gezeigt wird.

Theming

Das Theme folgt standardmäßig dem System. Umschalten durch Setzen von data-theme auf <html> (die Website speichert die Auswahl in localStorage als fp-theme und setzt sie in index.html vor dem ersten Rendern):

document.documentElement.setAttribute('data-theme', 'dark')  // oder 'light'

Schreiben Sie niemals themenspezifisches CSS in Komponenten. Wenn Sie das Aussehen global ändern müssen, bearbeiten Sie tokens/flatpack.tokens.json und führen Sie npm run build:tokens aus.

Anti-Patterns (nicht tun)

  • Erfinden einer neuen farbigen Primäraktion (z. B. einen blauen oder grünen CTA). Primär ist nur schwarz/nahweiß.
  • Hinzufügen von Schatten außerhalb schwebender Ebenen, Verläufen, Glas-Effekten, farbigen Füllungen oder einer zweiten Umrandung innerhalb einer Karte.
  • Abgerundete Ecken, Pillen-Buttons, Großbuchstaben-Monospace-Abschnittsbezeichnungen.
  • Festlegen von Hex-Werten in JSX anstelle von var(--fp-*).
  • Neuimplementierung von Button / Card / Input als gestylte <div>s — importieren Sie immer die Komponente.
  • Raten von Props (<Button color="red">, <Select items={...}>). Verwenden Sie die genauen Props in dieser Fertigkeit.
  • Hinzufügen von e-commerce-spezifischen Komponenten (Preisschilder, Produktkacheln) zur Basisbibliothek. Szenariospezifisches UI gehört in Blöcke, nicht in den Komponentensatz.

Arbeitsablauf

  1. Bestätigen Sie, dass das Zielprojekt Flatpack eingerichtet hat (Einrichtung oben); falls nicht, richten Sie es ein.
  2. Lesen Sie src/site/componentDocs.ts für jede Komponente, bei deren Props Sie unsicher sind — es ist die Quelle der Wahrheit.
  3. Setzen Sie den Bildschirm aus dem Inventar zusammen. Verwenden Sie Tailwind nur für Layout/Abstände.
  4. Überprüfen Sie das Ergebnis gegen die drei Regeln und führen Sie npm run check:design aus. Entfernen Sie alle fest codierten Werte, Schatten oder dekorativen Akzente, die Sie eingeführt haben.
  5. Stellen Sie sicher, dass es baut. Wenn Sie eine Komponente hinzugefügt haben, die nicht im Inventar ist, sagen Sie dies explizit und behalten Sie sie szenariospezifisch, anstatt sie zum Basisset hinzuzufügen.

Verwandte Skills