Zui
@zuccadev-labs/zuix-zui es el sistema de componentes de la suite: 64 componentes en 8 grupos. Cada
componente es un contrato de HTML y CSS que solo lee tokens, así que una marca nueva no modifica componentes
y el mismo marcado sirve en cualquier framework. El paquete trae dos formas de darle vida: el binding de
React y @zuccadev-labs/zuix-zui/dom, sin framework (Frameworks).
No depende de ninguna biblioteca de UI. En ejecución solo necesita @zuccadev-labs/zuix-tokens;
@zuccadev-labs/zuix-zicon es un peer obligatorio y React y React DOM 19 son peers opcionales.
El catálogo en vivo, con el código de cada ejemplo, está en Componentes.
Catálogo
| Grupo | Componentes |
|---|---|
| Acciones | Button, IconButton, Link, Toggle, SegmentedControl |
| Formularios | Field, Input, Textarea, Select, NativeSelect, Combobox, Checkbox, RadioGroup, Radio, Switch, Slider, DateInput, Calendar, DatePicker, OTPInput, FileUpload, SearchInput |
| Datos | Table, DataTable, Badge, Chip, Avatar, AvatarGroup, StatTile, Meter, Progress, Rating, Kbd |
| Estado | Spinner, Skeleton, LoadingOverlay, EmptyState, ErrorState, ErrorBoundary, Alert |
| Contenido | Card, CardHeader, CardFooter, Panel, Callout, CodeBlock, Divider |
| Capas | Modal, ConfirmDialog, Drawer, Popover, Tooltip, Menu, ContextMenu, CommandPalette, Toast |
| Navegación | Tabs, Breadcrumb, Pagination, Stepper, Accordion, Tree, NavList |
| Carousel | Carousel con efecto lente |
Cada componente declara en el contrato qué necesita para funcionar:
behavior | Significado | Cuántos |
|---|---|---|
none | Solo CSS. Basta el marcado | 34 |
dom | Necesita @zuccadev-labs/zuix-zui/dom, o el binding de React | 29 |
ErrorBoundary es el único que solo existe en React: es un límite de errores de React, no un marcado.
Uso con React
import "@zuccadev-labs/zuix-tokens/tokens.css";
import "@zuccadev-labs/zuix-zui/styles.css";
import "@zuccadev-labs/zuix-zicon/all";
import { Button, ToastProvider, useToast } from "@zuccadev-labs/zuix-zui";
function Save() {
const { toast } = useToast();
return <Button variant="primary" icon="check" onClick={() => toast({ title: "Saved", intent: "success" })}>Save</Button>;
}
export function App() {
return <ToastProvider><Save /></ToastProvider>;
}
ToastProviderenvuelve la aplicación una vez.- Los textos visibles llegan por props; los valores por defecto están en inglés.
- La clase
z-rooten el contenedor de la aplicación aplica tipografía, foco y selección. - Los componentes aceptan
refcomo prop, sinforwardRef: es la forma de React 19.
Con Next.js
Los módulos con hooks, contexto o manejadores propios llevan "use client"; los de solo marcado se
renderizan como Server Components. @zuccadev-labs/zuix-zicon/all se importa dos veces, en app/layout.tsx
y en un módulo con "use client", porque Next mantiene un registro de iconos por cada grafo. Ejemplo completo
en Frameworks.
Cómo están hechas las capas
| Pieza | Sobre qué va | Qué da el navegador |
|---|---|---|
Modal, Drawer, ConfirmDialog, CommandPalette, Popover modal | <dialog> abierto con showModal() | Capa superior, velo (::backdrop, transparente en el Popover) e inercia del resto de la página |
Popover, Tooltip, Menu, ContextMenu, Select, Combobox, DatePicker, avisos | Un elemento popover="manual" | Capa superior, sin z-index ni portales |
| Colocación junto al disparador | Una función propia, la misma en React y en el modo DOM | — |
Lo que el navegador no da lo pone la suite: retener el foco y devolverlo al cerrar, cerrar con Escape solo la capa de arriba, cerrar al interactuar fuera, bloquear el desplazamiento de la página y seguir al disparador cuando la página se desplaza.
El marcado que emite React es el del contrato: se puede copiar a una página sin React y funciona con
zui/dom. Por eso el velo de un diálogo se estiliza como dialog::backdrop y un selector de aplicación debe
escribir dialog.z-modal, no .z-modal[role=dialog].
Variantes y estados
- Intención:
primary,secondary,ghost,danger. Tamaño:sm,md,lg. - Todo componente interactivo define reposo, hover, foco, activo y deshabilitado.
ButtoneIconButtonconloadingllevanaria-disabled="true", nodisabled: no ejecutanonClickni envían el formulario, pero conservan el foco del teclado.Popoverexige nombre accesible en sus tipos:label, oaria-labelledbycon el id de un encabezado del panel.
Formularios
Fieldetiqueta su control con<label for>y, cuando el control no es etiquetable (RadioGroup,OTPInput,Slider), conaria-labelledby.useFieldLabel()lo expone para controles propios.Select,Checkbox,Switch,RadioGroupyDatePickerllevan un campo nativo oculto (.z-native-input): participan en el envío del formulario y vuelven a su valor inicial conform.reset().Select requiredyDatePicker requiredusan además la validación nativa: el formulario no se envía vacío.Slidercon varios tiradores envía un campo por tirador con el mismoname.FileUploadconnameconserva los archivos aceptados en el campo y el formulario los envía.
Dirección de escritura
Dentro de un contenedor con dir="rtl" las hojas se reflejan (usan propiedades lógicas), los iconos
direccionales se voltean y el teclado se invierte donde el patrón lo pide: en Tabs, Menu, Slider,
RadioGroup, SegmentedControl, Calendar, Tree y Rating la flecha izquierda avanza. La dirección se
lee del DOM; no hay proveedor ni prop.
Táctil
- Con el dedo como puntero principal (
pointer: coarse) los controlessmymdmiden 40 px de alto: sale del token--z-touch-target(Tokens). Checkbox, Radio y Switch ganan aire vertical; el Slider, los botones de cierre y las opciones de SegmentedControl amplían su zona de pulsación sin cambiar el dibujo. - Las estrellas de
Ratingde entrada miden al menos 24 × 24 px con cualquier puntero. - No llegan a 40 px los controles secundarios densos: días de
Calendaren contenedores estrechos, quitarChip, copiar deCodeBlocky enlaces en línea. - Los estilos de
:hoversolo se aplican donde hay hover (@media (hover: hover)). - Gestos: el Carousel se arrastra con inercia y deja pasar el desplazamiento vertical (
touch-action: pan-y); un Toast se descarta deslizándolo; el ContextMenu se abre con pulsación larga; Slider,SplitPaneyResizeHandlese arrastran con el dedo. Igual con React y conzui/dom.
Material
| Clase | Uso |
|---|---|
z-liquid | Cristal: paneles, barras, menús, diálogos |
z-solid | Superficie opaca para lectura y edición |
z-canvas | Fondo de aplicación sobre el que flota el cristal |
Con prefers-reduced-transparency o prefers-contrast: more el cristal pasa a opaco.
Carousel
<Carousel
ariaLabel="Featured projects"
items={projects}
getKey={(p) => p.id}
renderItem={(p, i, { active }) => <ProjectCard project={p} highlighted={active} />}
/>
| Modo | Cuándo |
|---|---|
css | Por defecto: deforma las diapositivas reales, sirve con cualquier contenido |
gl | Si se pasa rasterize y hay WebGL2: los bordes se dibujan en un lienzo. Sin React: data-raster (Frameworks) |
flat | Con effect="none" o movimiento reducido |
Arrastre con inercia, bucle infinito, flechas, teclado y anuncios para lectores de pantalla. Si el navegador
no ofrece WebGL2 se pregunta una sola vez por página y el carrusel sigue en css.
Reglas de uso
- No se pasan colores, radios ni sombras por
styleo clases sueltas. - Si una variante no existe, se añade al sistema.
- El cristal no se aplica sobre áreas de lectura o edición de texto.
- Los componentes de dominio (pagos, reservas, mapas) viven en la aplicación.
DataTablemuestra una fecha sinrendercontoLocaleDateString(). En render de servidor, con otra zona horaria o idioma que el navegador, eso produce un desajuste de hidratación: para fechas, pasarender.
Manifiestos
Cada componente tiene un *.manifest.json con props, valores permitidos, tokens que lee, clases y ejemplos
completos. pnpm manifest los valida y los reúne en zui/manifest.json; pnpm html genera zui/html.json
con el marcado de cada ejemplo. Los dos se publican con el paquete.
De dónde sale cada cosa
| Fuente | Aporta |
|---|---|
| WAI-ARIA Authoring Practices | Roles, teclado y foco de cada patrón |
| El design system de un proyecto privado anterior | Button, Input, DateInput, Card, Avatar, Chip, Rating, Meter, estados |
| zutool | Aspecto liquid glass, menús, paleta de comandos, controles |
ui-glass | Panel, StatTile, DataTable |
| La página de presentación de ese mismo proyecto | Carousel con efecto lente |
Las dos técnicas adaptadas de terceros (la zona de gracia del puntero en submenús y la prueba de punto en
polígono) llevan su aviso en THIRD_PARTY_NOTICES.md, dentro del paquete.
Qué está probado
Las pruebas y lo que cubre cada una están en Calidad y pruebas; los límites, en Accesibilidad y Compatibilidad.