Construire avec Flatpack UI
Flatpack UI est une bibliothèque de composants React 19 + Tailwind CSS 4. Les composants interactifs sont basés sur les primitives Base UI (sans style, accessibles) ; la couche visuelle est une seule feuille de style. Ses règles de conception sont carré, noir et blanc, espaces blancs. Construisez des écrans en composant les composants de la bibliothèque ; ne créez pas de <div> stylisés à la main quand un composant existe.
Quand l'utiliser
- L'utilisateur demande de construire une page / écran / tableau de bord / prototype et mentionne Flatpack UI ou cette bibliothèque de composants noir et blanc.
- L'utilisateur veut une interface utilisateur dans le langage visuel établi de ce projet.
- Ne pas utiliser pour une demande générique de type "crée-moi un site web" à moins que l'utilisateur ne nomme cette bibliothèque ou que le projet ne l'utilise déjà.
Configuration (à faire en premier)
Flatpack UI nécessite uniquement sa feuille de style et le code source des composants. Dans un projet cible :
- Copiez le thème et les composants depuis la racine de la bibliothèque :
src/styles/flatpack.css→ ciblesrc/styles/flatpack.csssrc/components/ui/*.tsx→ ciblesrc/components/ui/src/lib/utils.ts→ ciblesrc/lib/utils.ts
- Installez les dépendances si manquantes :
react@19 react-dom@19 @base-ui/react clsx tailwind-merge lucide-react. Tailwind CSS 4 et TypeScript sont attendus. Les composants interactifs (Button, Checkbox, Switch, RadioGroup, Select, Dialog, Sheet, DropdownMenu, Tabs, Tooltip, Popover, Progress, Avatar, Collapse, Segmented) sont basés sur les primitives Base UI ; les composants purement visuels sont autonomes. La distribution utilise le format de registre shadcn (registry.json+public/r/). - Importez le thème après Tailwind :
@import "tailwindcss"; @import "./styles/flatpack.css"; - Supprimez toutes les variables de couleur
:root/.darkstandard de shadcn — Flatpack définit les siennes.
Si le projet a déjà la bibliothèque configurée, sautez la configuration et allez directement à la composition des composants.
La règle qui compte
Ne codez jamais en dur les couleurs, les tailles, les espacements, les rayons ou les ombres. Chaque décision visuelle provient d'une variable CSS dans flatpack.css, générée à partir de tokens/flatpack.tokens.json. Les styles en ligne référencent uniquement des tokens : var(--fp-text-*) pour la taille de police (12/14/16/20/28/40/64/96), var(--fp-space-*) pour l'espacement (4 … 128), et les tokens de couleur --fp-bg, --fp-surface, --fp-line, --fp-line-strong, --fp-muted, --fp-ink, --fp-danger, --fp-success. npm run check:design échoue sur toute autre chose.
Les trois règles :
- Forme par rôle : les parties cliquables sur une seule ligne (Button, ChipGroup, Input, Select, Segmented, Badge, Switch, Tooltip, pagination) utilisent
--fp-radius-control(une pilule par défaut) ; les surfaces qui contiennent du contenu (Card, Image, Dialog, menus, Table, Toast, code, Textarea) utilisent--fp-radius-surface(0). Pas de rayons intermédiaires. Le préréglage "Tout carré" (data-fp-shape="square"ou shape: square dans les surcharges) rend les contrôles à 0 également. - Filtres et recherche : les chips de filtre séparés sont
<ChipGroup options={[{ value, label, count? }]} />; une boîte de recherche est<Input variant="filled" leading={<Search size={16} />} />; un bouton lien secondaire est<Button variant="outline">(anneau d'encre). - Noir et blanc : un accent par thème, et dans le thème par défaut il s'agit de l'encre (
--fp-accent). Pas de liens bleus (les liens sont en encre soulignée), pas de cyan, pas de dégradés. Le rouge et le vert apparaissent uniquement dans les textes de statut et les icônes, jamais en tant que remplissage. - Espaces blancs : séparez les sections avec de l'espace (au moins 96px entre les sections de page). Une seule bordure de 1px. Une carte ne contient jamais une deuxième boîte bordée. Seules les couches flottantes (Dialog, Popover, Select, Dropdown) ont une ombre.
Type : corps de texte 16px à 1.6, titres à 1.1, graisses 400/500/600. Monospace uniquement pour les chiffres, les ID et le code (.fp-num), jamais pour les titres de section ; pas d'étiquettes en majuscules. Les icônes sont lucide à 16px. L'interaction ne change que la couleur, jamais la position ; pas d'animation en boucle.
Pour afficher un bloc dans le thème opposé (par exemple une bannière en encre dont le bouton principal doit rester visible), ajoutez className="fp-invert".
Utilisez la classe .fp-label pour une petite légende grise ; utilisez <Kicker> pour une ligne grise simple au-dessus d'un titre.
Inventaire des composants
Toutes les importations proviennent de @/components/ui/<nom> (ajustez l'alias au projet cible).
| Besoin | Composant |
|---|---|
| Actions | Button, ButtonGroup / ToggleGroup / Toggle (toggle-group), Toolbar + ToolbarButton/ToolbarToggle/ToolbarGroup/ToolbarSeparator/ToolbarSpacer |
| Conteneurs | Card + CardHeader/CardTitle/CardDescription/CardContent/CardFooter |
| Étiquettes / statut | Badge, StatusDot (carré de 8px : default / success / danger / idle), Kbd / KbdGroup, Kicker (depuis primitives) |
| Saisie de texte | Input, Label, Textarea, NumberInput, Field / Fieldset / FieldControl (label + aide + erreur) |
| Choix | Select, Combobox (saisie anticipée), MultiSelect (chips), Checkbox, RadioGroup, Switch, Segmented, Slider (simple ou plage) |
| Dates / fichiers | Calendar, DatePicker, DateRangePicker, FileInput (collecte uniquement les fichiers) |
| Superpositions | Dialog, AlertDialog (confirmation ; danger pour destructif), Sheet, Popover, HoverCard, DropdownMenu, ContextMenu, Menubar, Tooltip, CommandPalette (⌘K), Lightbox / LightboxGallery |
| Commentaires | Alert, Toast (montez <Toaster /> une fois, appelez toast({ title, type })), Spinner, Skeleton + SkeletonText, Progress, Steps |
| Navigation | Tabs, Breadcrumb, Pagination, Sidebar + SidebarSection/SidebarItem |
| Affichage de données | Table (+ parties), DescriptionList, Tree, Image, Carousel, Avatar, AvatarGroup, Statistic, Timestamp, Collapse, Empty, CodeBlock / Code |
| Disposition / utilitaire | Divider, Separator (depuis primitives), ScrollArea, Masonry (cascade), VisuallyHidden, BorderBeam (ligne de bordure décorative optionnelle ; non utilisée par défaut car les règles n'ont pas d'animation en boucle) |
63 composants au total. Si un besoin n'est pas dans le tableau, composez à partir de ceux-ci avant d'ajouter une nouvelle source. Non fournis intentionnellement : éditeur de texte enrichi, moteur de rendu Markdown, Cascader, Transfer. Pour les écrans de chat IA, copiez le bloc assistant dans src/blocks/BlockScreens.tsx.
La densité, les polices et le gris chaud optionnel sont au niveau des tokens : définissez data-fp-density="compact" (ou data-fp-font, data-fp-heading, data-fp-gray) sur n'importe quel élément, ou écrivez un code de préréglage dans tokens/overrides.json et exécutez npm run build:tokens. Les thèmes (flatpack, catalog, sage) échangent la palette, l'accent, le rayon de surface et la pile de polices comme une unité : définissez data-fp-theme="sage" sur n'importe quel élément. Les états de remplissage et de sélection utilisent --fp-accent / --fp-on-accent, le texte utilise --fp-ink. N'ajoutez jamais de rayon, de couleur d'accent, d'ombre ou de flou ponctuel en dehors d'un thème.
Modèles copier-coller
Voici les props exactes. Utilisez-les telles quelles ; ne devinez pas les noms de props.
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'
// Boutons — variant : default | secondary | outline | ghost | link ; size : default | sm | lg | icon
<Button>Principal</Button>
<Button variant="outline" size="sm">Secondaire</Button>
<Button size="icon" aria-label="Rechercher"><Search size={16}/></Button>
// Badge — variant : default | outline | success | danger
<Badge>Nouveau</Badge><Badge variant="success">En stock</Badge>
// Formulaire
<Label>Nom</Label>
<Input placeholder="Tapez ici" />
// Carte
<Card>
<CardHeader><CardTitle>Titre</CardTitle><CardDescription>Sous-titre</CardDescription></CardHeader>
<CardContent>...</CardContent>
<CardFooter><Button size="sm">Action</Button></CardFooter>
</Card>
<Kicker>Accroche de section</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="Activé" />
<Checkbox indeterminate label="Partiel" />
<Checkbox disabled defaultChecked label="Verrouillé" />
<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: 'Jour' },
{ value: 'week', label: 'Semaine' },
]} />
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>Ouvrir</DialogTrigger>
<DialogContent>
<DialogHeader><DialogTitle>Titre</DialogTitle><DialogDescription>Détails</DialogDescription></DialogHeader>
<DialogFooter><DialogClose>Fermer</DialogClose></DialogFooter>
</DialogContent>
</Dialog>
<Sheet>
<SheetTrigger>Panier (2)</SheetTrigger>
<SheetContent title="Panier">...</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>Accueil</BreadcrumbLink></BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem><BreadcrumbCurrent>Actuel</BreadcrumbCurrent></BreadcrumbItem>
</Breadcrumb>
<Pagination total={96} pageSize={10} defaultValue={1} onValueChange={(p) => {}} />
<Alert variant="success" title="Enregistré">Vos modifications sont en ligne.</Alert>
<Progress value={64} label="Progression" showValue />
<Steps current={1} steps={[{ title: 'Début' }, { title: 'Configurer' }, { title: 'Terminé' }]} />
<Empty title="Rien ici" action={<Button size="sm">Créer</Button>} />
<Statistic label="Commandes" value="1 472" trend={{ value: 12.4 }} />
<Collapse items={[{ key: 'a', title: 'Question', children: 'Réponse' }]} />
<Divider label="ou" />
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>Éléments</TableCaption>
<TableHeader><TableRow><TableHead>Nom</TableHead><TableHead>Qté</TableHead></TableRow></TableHeader>
<TableBody><TableRow><TableCell>Widget</TableCell><TableCell>1</TableCell></TableRow></TableBody>
</Table>
<Image ratio="4:3" alt="Aperçu" 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} />
Les tableaux d'API complets pour chaque composant se trouvent dans le fichier src/site/componentDocs.ts de la bibliothèque et la documentation rendue à #/docs/components/:id. Lisez ce fichier lorsque vous avez besoin d'une prop qui n'est pas montrée ci-dessus.
Thématisation
Le thème suit le système par défaut. Basculez en définissant data-theme sur <html> (le site enregistre le choix dans localStorage sous fp-theme et le définit dans index.html avant le premier rendu) :
document.documentElement.setAttribute('data-theme', 'dark') // ou 'light'
N'écrivez jamais de CSS spécifique à un thème dans les composants. Si vous devez modifier l'apparence globalement, modifiez tokens/flatpack.tokens.json et exécutez npm run build:tokens.
Anti-patrons (à ne pas faire)
- Inventer une nouvelle action principale colorée (par exemple un CTA bleu ou vert). Le primaire est uniquement noir/blanc cassé.
- Ajouter des ombres en dehors des couches flottantes, des dégradés, des effets de verre, des remplissages colorés, ou une deuxième bordure à l'intérieur d'une carte.
- Coins arrondis, boutons en pilule, étiquettes de section en monospace majuscules.
- Coder en dur des valeurs hexadécimales dans JSX au lieu d'utiliser
var(--fp-*). - Réimplémenter
Button/Card/Inputen tant que<div>stylisés — importez toujours le composant. - Deviner les props (
<Button color="red">,<Select items={...}>). Utilisez les props exactes de cette compétence. - Ajouter des composants spécifiques au commerce électronique (étiquettes de prix, vignettes de produits) à la bibliothèque de base. L'interface utilisateur spécifique à un scénario appartient aux Blocs, pas à l'ensemble de composants.
Flux de travail
- Confirmez que le projet cible a Flatpack configuré (configuration ci-dessus) ; sinon, configurez-le.
- Lisez
src/site/componentDocs.tspour tout composant dont vous n'êtes pas sûr des props — c'est la source de vérité. - Composez l'écran à partir de l'inventaire. Utilisez Tailwind uniquement pour la disposition/l'espacement.
- Vérifiez le résultat par rapport aux trois règles et exécutez
npm run check:design. Supprimez toute valeur codée en dur, ombre ou accent décoratif que vous avez introduit. - Vérifiez qu'il se construit. Si vous avez ajouté un composant qui n'est pas dans l'inventaire, dites-le explicitement et gardez-le local au scénario plutôt que de l'ajouter à l'ensemble de base.