Construir com Flatpack UI
Flatpack UI é uma biblioteca de componentes React 19 + Tailwind CSS 4. Componentes interativos são construídos sobre primitivas Base UI (sem estilos, acessíveis); a camada visual é uma única folha de estilo. Suas regras de design são quadrado, preto e branco, espaços em branco. Construa telas compondo os componentes da biblioteca; não crie <div>s estilizados manualmente quando um componente existir.
Quando usar
- O usuário pede para construir uma página / tela / dashboard / protótipo e menciona Flatpack UI ou esta biblioteca de componentes preto e branco.
- O usuário quer uma interface na linguagem visual estabelecida do projeto.
- Não use para um pedido genérico de "faça um site" a menos que o usuário nomeie esta biblioteca ou o projeto já a utilize.
Configuração (faça isso primeiro)
Flatpack UI precisa apenas de sua folha de estilo e código-fonte dos componentes. Em um projeto de destino:
- Copie o tema e os componentes da raiz da biblioteca:
src/styles/flatpack.css→ destinosrc/styles/flatpack.csssrc/components/ui/*.tsx→ destinosrc/components/ui/src/lib/utils.ts→ destinosrc/lib/utils.ts
- Instale dependências se estiverem faltando:
react@19 react-dom@19 @base-ui/react clsx tailwind-merge lucide-react. Tailwind CSS 4 e TypeScript são esperados. Componentes interativos (Button, Checkbox, Switch, RadioGroup, Select, Dialog, Sheet, DropdownMenu, Tabs, Tooltip, Popover, Progress, Avatar, Collapse, Segmented) são construídos sobre primitivas Base UI; componentes puramente visuais são autocontidos. A distribuição usa o formato de registro shadcn (registry.json+public/r/). - Importe o tema após o Tailwind:
@import "tailwindcss"; @import "./styles/flatpack.css"; - Remova quaisquer variáveis de cor
:root/.darkdo shadcn padrão — Flatpack define as suas próprias.
Se o projeto já tiver a biblioteca configurada, pule a configuração e vá direto para compor componentes.
A única regra que importa
Nunca hardcode cores, tamanhos, espaçamentos, raios ou sombras. Toda decisão visual vem de uma variável CSS em flatpack.css, gerada a partir de tokens/flatpack.tokens.json. Estilos inline referenciam apenas tokens: var(--fp-text-*) para tamanho de fonte (12/14/16/20/28/40/64/96), var(--fp-space-*) para espaçamento (4 … 128), e os tokens de cor --fp-bg, --fp-surface, --fp-line, --fp-line-strong, --fp-muted, --fp-ink, --fp-danger, --fp-success. npm run check:design falha em qualquer outra coisa.
As três regras:
- Forma por função: partes clicáveis de linha única (Button, ChipGroup, Input, Select, Segmented, Badge, Switch, Tooltip, paginação) usam
--fp-radius-control(uma pílula por padrão); superfícies que contêm conteúdo (Card, Image, Dialog, menus, Table, Toast, código, Textarea) usam--fp-radius-surface(0). Sem raios intermediários. A predefinição "All square" (data-fp-shape="square"ou shape: square em overrides) torna os controles 0 também. - Filtros e pesquisa: chips de filtro separados são
<ChipGroup options={[{ value, label, count? }]} />; uma caixa de pesquisa é<Input variant="filled" leading={<Search size={16} />} />; um botão de link secundário é<Button variant="outline">(borda ink). - Preto e branco: um acento por tema, e no tema padrão é ink (
--fp-accent). Sem links azuis (links são ink sublinhado), sem ciano, sem gradientes. Vermelho e verde aparecem apenas em textos de status e ícones, nunca como preenchimento. - Espaços em branco: separe seções com espaço (pelo menos 96px entre seções da página). Uma borda de 1px. Um card nunca contém uma segunda caixa com borda. Apenas camadas flutuantes (Dialog, Popover, Select, Dropdown) têm sombra.
Tipo: corpo 16px com 1.6, títulos 1.1, pesos 400/500/600. Monoespaçado apenas para números, IDs e código (.fp-num), nunca para títulos de seção; sem rótulos em maiúsculas. Ícones são lucide com 16px. Interação muda apenas cor, nunca posição; sem animação em loop.
Para renderizar um bloco no tema oposto (por exemplo, um banner ink cujo botão principal deve permanecer visível), adicione className="fp-invert".
Use a classe .fp-label para uma legenda cinza pequena; use <Kicker> para uma linha cinza simples acima de um título.
Inventário de componentes
Todas as importações são de @/components/ui/<nome> (ajuste o alias para o projeto de destino).
| Necessidade | Componente |
|---|---|
| Ações | Button, ButtonGroup / ToggleGroup / Toggle (toggle-group), Toolbar + ToolbarButton/ToolbarToggle/ToolbarGroup/ToolbarSeparator/ToolbarSpacer |
| Contêineres | Card + CardHeader/CardTitle/CardDescription/CardContent/CardFooter |
| Rótulos / status | Badge, StatusDot (quadrado 8px: default / success / danger / idle), Kbd / KbdGroup, Kicker (de primitives) |
| Entrada de texto | Input, Label, Textarea, NumberInput, Field / Fieldset / FieldControl (label + ajuda + erro) |
| Escolha | Select, Combobox (typeahead), MultiSelect (chips), Checkbox, RadioGroup, Switch, Segmented, Slider (único ou intervalo) |
| Datas / arquivos | Calendar, DatePicker, DateRangePicker, FileInput (coleta apenas arquivos) |
| Sobreposições | Dialog, AlertDialog (confirmar; danger para destrutivo), Sheet, Popover, HoverCard, DropdownMenu, ContextMenu, Menubar, Tooltip, CommandPalette (⌘K), Lightbox / LightboxGallery |
| Feedback | Alert, Toast (monte <Toaster /> uma vez, chame toast({ title, type })), Spinner, Skeleton + SkeletonText, Progress, Steps |
| Navegação | Tabs, Breadcrumb, Pagination, Sidebar + SidebarSection/SidebarItem |
| Exibição de dados | Table (+ partes), DescriptionList, Tree, Image, Carousel, Avatar, AvatarGroup, Statistic, Timestamp, Collapse, Empty, CodeBlock / Code |
| Layout / utilidade | Divider, Separator (de primitives), ScrollArea, Masonry (cachoeira), VisuallyHidden, BorderBeam (linha de borda decorativa opcional; não usada por padrão porque as regras não têm animação em loop) |
63 componentes no total. Se uma necessidade não estiver na tabela, componha a partir destes antes de adicionar nova fonte. Não fornecidos propositalmente: editor rich text, renderizador Markdown, Cascader, Transfer. Para telas de chat de IA, copie o bloco assistant em src/blocks/BlockScreens.tsx.
Densidade, fontes e o cinza quente opcional são de nível de token: defina data-fp-density="compact" (ou data-fp-font, data-fp-heading, data-fp-gray) em qualquer elemento, ou escreva um código de predefinição em tokens/overrides.json e execute npm run build:tokens. Temas (flatpack, catalog, sage) trocam paleta, acento, raio de superfície e pilha de fontes como uma unidade: defina data-fp-theme="sage" em qualquer elemento. Estados preenchidos e selecionados usam --fp-accent / --fp-on-accent, texto usa --fp-ink. Nunca adicione raio, cores de acento, sombras ou desfoque únicos fora de um tema.
Padrões de copy-paste
Estas são as props exatas. Use-as como estão; não adivinhe nomes 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'
// Botões — variant: default | secondary | outline | ghost | link; size: default | sm | lg | icon
<Button>Primário</Button>
<Button variant="outline" size="sm">Secundário</Button>
<Button size="icon" aria-label="Pesquisar"><Search size={16}/></Button>
// Badge — variant: default | outline | success | danger
<Badge>Novo</Badge><Badge variant="success">Em estoque</Badge>
// Formulário
<Label>Nome</Label>
<Input placeholder="Digite aqui" />
// Card
<Card>
<CardHeader><CardTitle>Título</CardTitle><CardDescription>Subtítulo</CardDescription></CardHeader>
<CardContent>...</CardContent>
<CardFooter><Button size="sm">Ação</Button></CardFooter>
</Card>
<Kicker>Linha acima do título</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="Ativado" />
<Checkbox indeterminate label="Parcial" />
<Checkbox disabled defaultChecked label="Bloqueado" />
<RadioGroup defaultValue="a" options={[
{ value: 'a', label: 'Opção A' },
{ value: 'b', label: 'Opção B', disabled: true },
]} />
<Switch defaultChecked label="Notificações" />
<Segmented defaultValue="day" options={[
{ value: 'day', label: 'Dia' },
{ value: 'week', label: 'Semana' },
]} />
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>Abrir</DialogTrigger>
<DialogContent>
<DialogHeader><DialogTitle>Título</DialogTitle><DialogDescription>Detalhes</DialogDescription></DialogHeader>
<DialogFooter><DialogClose>Fechar</DialogClose></DialogFooter>
</DialogContent>
</Dialog>
<Sheet>
<SheetTrigger>Carrinho (2)</SheetTrigger>
<SheetContent title="Carrinho">...</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>Início</BreadcrumbLink></BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem><BreadcrumbCurrent>Atual</BreadcrumbCurrent></BreadcrumbItem>
</Breadcrumb>
<Pagination total={96} pageSize={10} defaultValue={1} onValueChange={(p) => {}} />
<Alert variant="success" title="Salvo">Suas alterações estão no ar.</Alert>
<Progress value={64} label="Progresso" showValue />
<Steps current={1} steps={[{ title: 'Início' }, { title: 'Configurar' }, { title: 'Concluído' }]} />
<Empty title="Nada aqui" action={<Button size="sm">Criar</Button>} />
<Statistic label="Pedidos" value="1.472" trend={{ value: 12.4 }} />
<Collapse items={[{ key: 'a', title: 'Pergunta', children: 'Resposta' }]} />
<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>Itens</TableCaption>
<TableHeader><TableRow><TableHead>Nome</TableHead><TableHead>Qtd</TableHead></TableRow></TableHeader>
<TableBody><TableRow><TableCell>Widget</TableCell><TableCell>1</TableCell></TableRow></TableBody>
</Table>
<Image ratio="4:3" alt="Visualização" 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} />
Tabelas de API completas para cada componente estão em src/site/componentDocs.ts da biblioteca e na documentação renderizada em #/docs/components/:id. Leia esse arquivo quando precisar de uma prop que não está mostrada acima.
Temas
O tema segue o sistema por padrão. Alterne definindo data-theme no <html> (o site salva a escolha em localStorage como fp-theme e a define em index.html antes da primeira renderização):
document.documentElement.setAttribute('data-theme', 'dark') // ou 'light'
Nunca escreva CSS específico de tema em componentes. Se precisar alterar a aparência globalmente, edite tokens/flatpack.tokens.json e execute npm run build:tokens.
Anti-padrões (não faça isso)
- Inventar uma nova ação primária colorida (ex.: um CTA azul ou verde). Primário é apenas preto/quase branco.
- Adicionar sombras fora de camadas flutuantes, gradientes, efeitos de vidro, preenchimentos coloridos ou uma segunda borda dentro de um card.
- Cantos arredondados, botões em pílula, rótulos de seção em maiúsculas e monoespaçados.
- Hardcodar valores hex em JSX em vez de usar
var(--fp-*). - Reimplementar
Button/Card/Inputcomo<div>s estilizados — sempre importe o componente. - Adivinhar props (
<Button color="red">,<Select items={...}>). Use as props exatas nesta habilidade. - Adicionar componentes específicos de e-commerce (etiquetas de preço, blocos de produto) à biblioteca base. UI específica de cenário pertence a Blocks, não ao conjunto de componentes.
Fluxo de trabalho
- Confirme que o projeto de destino tem Flatpack configurado (setup acima); se não, configure-o.
- Leia
src/site/componentDocs.tspara qualquer componente cujas props você não tenha certeza — é a fonte da verdade. - Componha a tela a partir do inventário. Use Tailwind apenas para layout/espaçamento.
- Verifique o resultado contra as três regras e execute
npm run check:design. Remova qualquer valor hardcoded, sombra ou acento decorativo que você introduziu. - Verifique se compila. Se você adicionou um componente que não está no inventário, diga isso explicitamente e mantenha-o local ao cenário, em vez de adicioná-lo ao conjunto base.