flatpack-ui

Habilidade de codificação. Construa interfaces com Flatpack UI, uma biblioteca de componentes React cujas regras de design são moldadas pela função (controles em pílula, superfícies quadradas), preto e branco, e espaços em branco.

O que é flatpack-ui?

Esta habilidade capacita um agente de IA a construir interfaces de usuário completas usando a biblioteca Flatpack UI, um conjunto de componentes React 19 + Tailwind CSS 4 com um sistema de design rigoroso baseado em regras visuais consistentes: formas definidas pela função do elemento (controles em pílula para ações, superfícies quadradas para conteúdo), paleta monocromática (preto e branco) e espaçamento generoso. O agente pode compor telas, dashboards e protótipos combinando mais de 60 componentes pré-construídos (botões, cartões, formulários, tabelas, diálogos, etc.), em vez de criar estilos do zero. A habilidade impõe automaticamente as regras de design do Flatpack, como nunca usar cores hardcoded (sempre variáveis CSS), não adicionar sombras fora de camadas flutuantes, e manter bordas, cantos e tipografia consistentes. Ela funciona em qualquer projeto Next.js ou React que siga a configuração de setup fornecida, e inclui padrões de copy-paste exatos para os componentes mais comuns. O agente usa esta habilidade sempre que o usuário menciona Flatpack UI, a biblioteca preto-e-branco, ou pede para construir uma página ou protótipo neste estilo visual.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. Copie o tema e os componentes da raiz da biblioteca:
    • src/styles/flatpack.css → destino src/styles/flatpack.css
    • src/components/ui/*.tsx → destino src/components/ui/
    • src/lib/utils.ts → destino src/lib/utils.ts
  2. 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/).
  3. Importe o tema após o Tailwind:
    @import "tailwindcss";
    @import "./styles/flatpack.css";
    
  4. Remova quaisquer variáveis de cor :root / .dark do 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).

NecessidadeComponente
AçõesButton, ButtonGroup / ToggleGroup / Toggle (toggle-group), Toolbar + ToolbarButton/ToolbarToggle/ToolbarGroup/ToolbarSeparator/ToolbarSpacer
ContêineresCard + CardHeader/CardTitle/CardDescription/CardContent/CardFooter
Rótulos / statusBadge, StatusDot (quadrado 8px: default / success / danger / idle), Kbd / KbdGroup, Kicker (de primitives)
Entrada de textoInput, Label, Textarea, NumberInput, Field / Fieldset / FieldControl (label + ajuda + erro)
EscolhaSelect, Combobox (typeahead), MultiSelect (chips), Checkbox, RadioGroup, Switch, Segmented, Slider (único ou intervalo)
Datas / arquivosCalendar, DatePicker, DateRangePicker, FileInput (coleta apenas arquivos)
SobreposiçõesDialog, AlertDialog (confirmar; danger para destrutivo), Sheet, Popover, HoverCard, DropdownMenu, ContextMenu, Menubar, Tooltip, CommandPalette (⌘K), Lightbox / LightboxGallery
FeedbackAlert, Toast (monte <Toaster /> uma vez, chame toast({ title, type })), Spinner, Skeleton + SkeletonText, Progress, Steps
NavegaçãoTabs, Breadcrumb, Pagination, Sidebar + SidebarSection/SidebarItem
Exibição de dadosTable (+ partes), DescriptionList, Tree, Image, Carousel, Avatar, AvatarGroup, Statistic, Timestamp, Collapse, Empty, CodeBlock / Code
Layout / utilidadeDivider, 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 / Input como <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

  1. Confirme que o projeto de destino tem Flatpack configurado (setup acima); se não, configure-o.
  2. Leia src/site/componentDocs.ts para qualquer componente cujas props você não tenha certeza — é a fonte da verdade.
  3. Componha a tela a partir do inventário. Use Tailwind apenas para layout/espaçamento.
  4. 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.
  5. 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.

Habilidades Relacionadas