CommunityProgramación y desarrollogithub.com

flatpack-ui

Habilidad de código. Construye interfaces con Flatpack UI, una librería de componentes React cuyas reglas de diseño se basan en el rol (controles tipo píldora, superficies cuadradas), blanco y negro, y espacio en blanco.

¿Qué es flatpack-ui?

Flatpack UI es una habilidad de agente de IA diseñada para construir interfaces de usuario con una librería de componentes React 19 + Tailwind CSS 4 que sigue un sistema de diseño estricto basado en roles: los controles de una línea (botones, entradas, etc.) usan radio de píldora, mientras que las superficies que contienen contenido (tarjetas, diálogos, menús) usan radio cero. El diseño se adhiere a una paleta monocromática (blanco y negro con un acento por tema), sin sombras fuera de capas flotantes, sin gradientes, sin azules y sin animaciones en bucle. La habilidad proporciona un inventario completo de 63 componentes, reglas de lenguaje de diseño detalladas y patrones de copiar y pegar con props exactas para que el agente genere interfaces funcionales y consistentes con la marca sin necesidad de inventar APIs. Soporta proyectos React con TypeScript y Tailwind CSS 4, y utiliza variables CSS (--fp-*) para todas las decisiones visuales, asegurando que el diseño permanezca tokenizado y verificable mediante una herramienta de diseño ('check:design').

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Construir con Flatpack UI

Flatpack UI es una librería de componentes React 19 + Tailwind CSS 4. Los componentes interactivos se basan en primitivas Base UI (sin estilos, accesibles); la capa visual es una única hoja de estilos. Sus reglas de diseño son cuadrado, blanco y negro, espacio en blanco. Construye pantallas componiendo los componentes de la librería; no crees <div>s con estilos manuales cuando exista un componente.

Cuándo usarlo

  • El usuario pide construir una página / pantalla / dashboard / prototipo y menciona Flatpack UI o esta librería de componentes en blanco y negro.
  • El usuario quiere una interfaz en el lenguaje visual establecido del proyecto.
  • No uses para una solicitud genérica de "hazme un sitio web" a menos que el usuario nombre esta librería o el proyecto ya la use.

Configuración (haz esto primero)

Flatpack UI solo necesita su hoja de estilos y el código fuente de los componentes. En un proyecto destino:

  1. Copia el tema y los componentes desde la raíz de la librería:
    • 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. Instala las dependencias si faltan: react@19 react-dom@19 @base-ui/react clsx tailwind-merge lucide-react. Se espera Tailwind CSS 4 y TypeScript. Los componentes interactivos (Button, Checkbox, Switch, RadioGroup, Select, Dialog, Sheet, DropdownMenu, Tabs, Tooltip, Popover, Progress, Avatar, Collapse, Segmented) se basan en primitivas Base UI; los componentes puramente visuales son autónomos. La distribución usa el formato de registro shadcn (registry.json + public/r/).
  3. Importa el tema después de Tailwind:
    @import "tailwindcss";
    @import "./styles/flatpack.css";
    
  4. Elimina cualquier variable de color :root / .dark de shadcn estándar — Flatpack define las suyas propias.

Si el proyecto ya tiene la librería configurada, omite la configuración y ve directamente a componer componentes.

La única regla que importa

Nunca codifiques colores, tamaños, espaciados, radios o sombras. Cada decisión visual proviene de una variable CSS en flatpack.css, generada desde tokens/flatpack.tokens.json. Los estilos en línea solo referencian tokens: var(--fp-text-*) para tamaño de fuente (12/14/16/20/28/40/64/96), var(--fp-space-*) para espaciado (4 … 128), y los tokens de color --fp-bg, --fp-surface, --fp-line, --fp-line-strong, --fp-muted, --fp-ink, --fp-danger, --fp-success. npm run check:design falla si se usa otra cosa.

Las tres reglas:

  • Forma según el rol: las partes cliqueables de una sola línea (Button, ChipGroup, Input, Select, Segmented, Badge, Switch, Tooltip, paginación) usan --fp-radius-control (una píldora por defecto); las superficies que contienen contenido (Card, Image, Dialog, menús, Table, Toast, código, Textarea) usan --fp-radius-surface (0). Sin radios intermedios. El preajuste "Todo cuadrado" (data-fp-shape="square" o shape: square en anulaciones) hace que los controles también sean 0.
  • Filtros y búsqueda: los chips de filtro separados son <ChipGroup options={[{ value, label, count? }]} />; un cuadro de búsqueda es <Input variant="filled" leading={<Search size={16} />} />; un botón de enlace secundario es <Button variant="outline"> (anillo de tinta).
  • Blanco y negro: un acento por tema, y en el tema por defecto es tinta (--fp-accent). Sin enlaces azules (los enlaces son tinta subrayada), sin cian, sin degradados. El rojo y el verde aparecen solo en textos de estado e iconos, nunca como relleno.
  • Espacio en blanco: separa las secciones con espacio (al menos 96px entre secciones de página). Un borde de 1px. Una tarjeta nunca contiene una segunda caja con borde. Solo las capas flotantes (Dialog, Popover, Select, Dropdown) tienen sombra.

Tipo: cuerpo 16px a 1.6, encabezados 1.1, pesos 400/500/600. Monoespaciado solo para números, IDs y código (.fp-num), nunca para títulos de sección; sin etiquetas en mayúsculas. Los iconos son lucide a 16px. La interacción cambia solo el color, nunca la posición; sin animación en bucle.

Para renderizar un bloque en el tema opuesto (por ejemplo, un banner de tinta cuyo botón principal debe permanecer visible), añade className="fp-invert".

Usa la clase .fp-label para una pequeña leyenda gris; usa <Kicker> para una línea gris simple encima de un encabezado.

Inventario de componentes

Todas las importaciones son de @/components/ui/<nombre> (ajusta el alias al proyecto destino).

NecesidadComponente
AccionesButton, ButtonGroup / ToggleGroup / Toggle (toggle-group), Toolbar + ToolbarButton/ToolbarToggle/ToolbarGroup/ToolbarSeparator/ToolbarSpacer
ContenedoresCard + CardHeader/CardTitle/CardDescription/CardContent/CardFooter
Etiquetas / estadoBadge, StatusDot (cuadrado de 8px: default / success / danger / idle), Kbd / KbdGroup, Kicker (de primitives)
Entrada de textoInput, Label, Textarea, NumberInput, Field / Fieldset / FieldControl (label + help + error)
ElecciónSelect, Combobox (typeahead), MultiSelect (chips), Checkbox, RadioGroup, Switch, Segmented, Slider (simple o rango)
Fechas / archivosCalendar, DatePicker, DateRangePicker, FileInput (solo recoge archivos)
SuperposicionesDialog, AlertDialog (confirmar; danger para destructivo), Sheet, Popover, HoverCard, DropdownMenu, ContextMenu, Menubar, Tooltip, CommandPalette (⌘K), Lightbox / LightboxGallery
RetroalimentaciónAlert, Toast (monta <Toaster /> una vez, llama a toast({ title, type })), Spinner, Skeleton + SkeletonText, Progress, Steps
NavegaciónTabs, Breadcrumb, Pagination, Sidebar + SidebarSection/SidebarItem
Visualización de datosTable (+ partes), DescriptionList, Tree, Image, Carousel, Avatar, AvatarGroup, Statistic, Timestamp, Collapse, Empty, CodeBlock / Code
Diseño / utilidadDivider, Separator (de primitives), ScrollArea, Masonry (cascada), VisuallyHidden, BorderBeam (borde decorativo opcional; no se usa por defecto porque las reglas no tienen animación en bucle)

63 componentes en total. Si una necesidad no está en la tabla, compón a partir de estos antes de añadir nuevo código fuente. No proporcionados a propósito: editor de texto enriquecido, renderizador de Markdown, Cascader, Transfer. Para pantallas de chat de IA, copia el bloque assistant en src/blocks/BlockScreens.tsx.

La densidad, las fuentes y el gris cálido opcional están a nivel de token: establece data-fp-density="compact" (o data-fp-font, data-fp-heading, data-fp-gray) en cualquier elemento, o escribe un código preajustado en tokens/overrides.json y ejecuta npm run build:tokens. Los temas (flatpack, catalog, sage) intercambian paleta, acento, radio de superficie y pila de fuentes como una unidad: establece data-fp-theme="sage" en cualquier elemento. Los estados de relleno y selección usan --fp-accent / --fp-on-accent, el texto usa --fp-ink. Nunca añadas radios, colores de acento, sombras o desenfoques únicos fuera de un tema.

Patrones de copiar y pegar

Estas son las props exactas. Úsalas tal cual; no adivines nombres 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'

// Botones — variant: default | secondary | outline | ghost | link; size: default | sm | lg | icon
<Button>Primario</Button>
<Button variant="outline" size="sm">Secundario</Button>
<Button size="icon" aria-label="Buscar"><Search size={16}/></Button>

// Badge — variant: default | outline | success | danger
<Badge>Nuevo</Badge><Badge variant="success">En stock</Badge>

// Formulario
<Label>Nombre</Label>
<Input placeholder="Escribe aquí" />

// Tarjeta
<Card>
  <CardHeader><CardTitle>Título</CardTitle><CardDescription>Subtítulo</CardDescription></CardHeader>
  <CardContent>...</CardContent>
  <CardFooter><Button size="sm">Acción</Button></CardFooter>
</Card>

<Kicker>Cejuela de sección</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="Habilitado" />
<Checkbox indeterminate label="Parcial" />
<Checkbox disabled defaultChecked label="Bloqueado" />

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

<Switch defaultChecked label="Notificaciones" />

<Segmented defaultValue="day" options={[
  { value: 'day', label: 'Día' },
  { 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>Detalles</DialogDescription></DialogHeader>
    <DialogFooter><DialogClose>Cerrar</DialogClose></DialogFooter>
  </DialogContent>
</Dialog>

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

<Pagination total={96} pageSize={10} defaultValue={1} onValueChange={(p) => {}} />
<Alert variant="success" title="Guardado">Tus cambios están en vivo.</Alert>
<Progress value={64} label="Progreso" showValue />
<Steps current={1} steps={[{ title: 'Inicio' }, { title: 'Configurar' }, { title: 'Listo' }]} />
<Empty title="Nada aquí" action={<Button size="sm">Crear</Button>} />
<Statistic label="Pedidos" value="1,472" trend={{ value: 12.4 }} />
<Collapse items={[{ key: 'a', title: 'Pregunta', children: 'Respuesta' }]} />
<Divider label="o" />
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>Elementos</TableCaption>
  <TableHeader><TableRow><TableHead>Nombre</TableHead><TableHead>Cant</TableHead></TableRow></TableHeader>
  <TableBody><TableRow><TableCell>Widget</TableCell><TableCell>1</TableCell></TableRow></TableBody>
</Table>

<Image ratio="4:3" alt="Vista previa" src="/x.jpg" />   {/* ratios: square | 4:3 | 16:9 | 3:4 */}
<Avatar size="md" name="Alicia" />
<Skeleton circle width={40} height={40} />
<SkeletonText lines={3} />

Las tablas de API completas para cada componente están en src/site/componentDocs.ts de la librería y en la documentación renderizada en #/docs/components/:id. Lee ese archivo cuando necesites una prop que no se muestra arriba.

Tematización

El tema sigue el sistema por defecto. Cambia estableciendo data-theme en <html> (el sitio guarda la elección en localStorage como fp-theme y la establece en index.html antes del primer pintado):

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

Nunca escribas CSS específico de tema en los componentes. Si necesitas cambiar la apariencia globalmente, edita tokens/flatpack.tokens.json y ejecuta npm run build:tokens.

Anti-patrones (no hagas esto)

  • Inventar una nueva acción primaria de color (por ejemplo, un CTA azul o verde). El primario es solo negro/blanco casi puro.
  • Añadir sombras fuera de capas flotantes, degradados, efectos de vidrio, rellenos de color o un segundo borde dentro de una tarjeta.
  • Esquinas redondeadas, botones píldora, etiquetas de sección en monoespaciado mayúsculas.
  • Codificar valores hexadecimales en JSX en lugar de usar var(--fp-*).
  • Reimplementar Button / Card / Input como <div>s con estilo — siempre importa el componente.
  • Adivinar props (<Button color="red">, <Select items={...}>). Usa las props exactas de esta habilidad.
  • Añadir componentes específicos de comercio electrónico (etiquetas de precio, mosaicos de producto) a la librería base. La interfaz de usuario específica del escenario pertenece a Blocks, no al conjunto de componentes.

Flujo de trabajo

  1. Confirma que el proyecto destino tiene Flatpack configurado (configuración arriba); si no, configúralo.
  2. Lee src/site/componentDocs.ts para cualquier componente del que no estés seguro de sus props — es la fuente de verdad.
  3. Compone la pantalla a partir del inventario. Usa Tailwind solo para diseño/espaciado.
  4. Verifica el resultado contra las tres reglas y ejecuta npm run check:design. Elimina cualquier valor codificado, sombra o acento decorativo que hayas introducido.
  5. Verifica que se compile. Si añadiste un componente que no está en el inventario, dílo explícitamente y mantenlo local al escenario en lugar de añadirlo al conjunto base.

Skills relacionados