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:
- Kopieren Sie das Theme und die Komponenten aus dem Bibliotheksstamm:
src/styles/flatpack.css→ Zielsrc/styles/flatpack.csssrc/components/ui/*.tsx→ Zielsrc/components/ui/src/lib/utils.ts→ Zielsrc/lib/utils.ts
- 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/). - Importieren Sie das Theme nach Tailwind:
@import "tailwindcss"; @import "./styles/flatpack.css"; - Entfernen Sie alle Standard-
:root/.darkFarbvariablen 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).
| Bedarf | Komponente |
|---|---|
| Aktionen | Button, ButtonGroup / ToggleGroup / Toggle (toggle-group), Toolbar + ToolbarButton/ToolbarToggle/ToolbarGroup/ToolbarSeparator/ToolbarSpacer |
| Container | Card + CardHeader/CardTitle/CardDescription/CardContent/CardFooter |
| Labels / Status | Badge, StatusDot (8px quadratisch: default / success / danger / idle), Kbd / KbdGroup, Kicker (aus primitives) |
| Texteingabe | Input, Label, Textarea, NumberInput, Field / Fieldset / FieldControl (Label + Hilfe + Fehler) |
| Auswahl | Select, Combobox (Typeahead), MultiSelect (Chips), Checkbox, RadioGroup, Switch, Segmented, Slider (einfach oder Bereich) |
| Daten / Dateien | Calendar, DatePicker, DateRangePicker, FileInput (sammelt nur Dateien) |
| Überlagerungen | Dialog, AlertDialog (bestätigen; danger für destruktiv), Sheet, Popover, HoverCard, DropdownMenu, ContextMenu, Menubar, Tooltip, CommandPalette (⌘K), Lightbox / LightboxGallery |
| Rückmeldung | Alert, Toast (mounten Sie <Toaster /> einmal, rufen Sie toast({ title, type }) auf), Spinner, Skeleton + SkeletonText, Progress, Steps |
| Navigation | Tabs, Breadcrumb, Pagination, Sidebar + SidebarSection/SidebarItem |
| Datenanzeige | Table (+ Teile), DescriptionList, Tree, Image, Carousel, Avatar, AvatarGroup, Statistic, Timestamp, Collapse, Empty, CodeBlock / Code |
| Layout / Dienstprogramm | Divider, 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/Inputals 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
- Bestätigen Sie, dass das Zielprojekt Flatpack eingerichtet hat (Einrichtung oben); falls nicht, richten Sie es ein.
- Lesen Sie
src/site/componentDocs.tsfür jede Komponente, bei deren Props Sie unsicher sind — es ist die Quelle der Wahrheit. - Setzen Sie den Bildschirm aus dem Inventar zusammen. Verwenden Sie Tailwind nur für Layout/Abstände.
- Überprüfen Sie das Ergebnis gegen die drei Regeln und führen Sie
npm run check:designaus. Entfernen Sie alle fest codierten Werte, Schatten oder dekorativen Akzente, die Sie eingeführt haben. - 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.