Sistema de Diseño con Radix UI
Construye sistemas de diseño accesibles y listos para producción utilizando los componentes primitivos de Radix UI, con control total de personalización y sin opiniones de estilo.
Resumen
Radix UI proporciona componentes accesibles sin estilo (primitivas) que puedes personalizar para que coincidan con cualquier sistema de diseño. Esta habilidad te guía en la construcción de bibliotecas de componentes escalables con Radix UI, centrándose en el diseño que prioriza la accesibilidad, la arquitectura de tematización y los patrones componibles.
Fortalezas Clave:
- Headless por diseño: Control de estilo total sin luchar contra valores predeterminados
- Accesibilidad incorporada: Cumplimiento WAI-ARIA, navegación por teclado, soporte para lectores de pantalla
- Primitivas componibles: Construye componentes complejos a partir de bloques de construcción simples
- Independiente del framework: Funciona con React, pero los estilos funcionan en cualquier lugar
Cuándo Usar Esta Habilidad
- Crear un sistema de diseño personalizado desde cero
- Construir bibliotecas de componentes de UI accesibles
- Implementar componentes interactivos complejos (Diálogo, Menú Desplegable, Pestañas, etc.)
- Migrar desde bibliotecas de componentes con estilo a primitivas sin estilo
- Configurar sistemas de tematización con variables CSS o Tailwind
- Necesitar control total sobre el comportamiento y estilo de los componentes
- Construir aplicaciones que requieran cumplimiento WCAG 2.1 AA/AAA
No uses esta habilidad cuando
- Necesites componentes preestilizados listos para usar (usa shadcn/ui, Mantine, etc.)
- Estés construyendo páginas estáticas simples sin interactividad
- El proyecto no utilice React 16.8+ (Radix requiere hooks)
- Necesites componentes para frameworks que no sean React
Principios Fundamentales
1. Accesibilidad Primero
Cada primitiva de Radix está construida con la accesibilidad como base:
- Navegación por Teclado: Soporte completo de teclado (Tabulador, Flechas, Enter, Escape)
- Lectores de Pantalla: Atributos ARIA adecuados y regiones en vivo
- Gestión de Enfoque: Captura y restauración automática del enfoque
- Estados Deshabilitados: Manejo adecuado de disabled y aria-disabled
Regla: Nunca sobrescribas las funciones de accesibilidad. Mejora, no reemplaces.
2. Arquitectura Headless
Radix proporciona comportamiento, tú proporcionas apariencia:
// ❌ No luches contra componentes preestilizados
<Button className="override-everything" />
// ✅ Radix te da comportamiento, tú agregas estilo
<Dialog.Root>
<Dialog.Trigger className="tus-estilos-boton" />
<Dialog.Content className="tus-estilos-modal" />
</Dialog.Root>
3. Composición sobre Configuración
Construye componentes complejos a partir de primitivas simples:
// Los componentes primitivos se componen naturalmente
<Tabs.Root>
<Tabs.List>
<Tabs.Trigger value="tab1">Pestaña 1</Tabs.Trigger>
<Tabs.Trigger value="tab2">Pestaña 2</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="tab1">Contenido 1</Tabs.Content>
<Tabs.Content value="tab2">Contenido 2</Tabs.Content>
</Tabs.Root>
Comenzando
Instalación
# Instalar primitivas individuales (recomendado)
npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu
# O instalar varias a la vez
npm install @radix-ui/react-{dialog,dropdown-menu,tabs,tooltip}
# Para estilos (opcional pero común)
npm install clsx tailwind-merge class-variance-authority
Patrón Básico de Componente
Cada componente de Radix sigue este patrón:
import * as Dialog from '@radix-ui/react-dialog';
export function MiDialogo() {
return (
<Dialog.Root>
{/* Disparador del diálogo */}
<Dialog.Trigger asChild>
<button className="estilos-disparador">Abrir</button>
</Dialog.Trigger>
{/* Portal renderiza fuera de la jerarquía del DOM */}
<Dialog.Portal>
{/* Superposición (fondo) */}
<Dialog.Overlay className="estilos-superposicion" />
{/* Contenido (modal) */}
<Dialog.Content className="estilos-contenido">
<Dialog.Title>Título</Dialog.Title>
<Dialog.Description>Descripción</Dialog.Description>
{/* Tu contenido aquí */}
<Dialog.Close asChild>
<button>Cerrar</button>
</Dialog.Close>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
);
}
Estrategias de Tematización
Estrategia 1: Variables CSS (Independiente del Framework)
Mejor para: Portabilidad máxima, compatible con SSR
/* globals.css */
:root {
--color-primary: 220 90% 56%;
--color-surface: 0 0% 100%;
--radius-base: 0.5rem;
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
}
[data-theme="dark"] {
--color-primary: 220 90% 66%;
--color-surface: 222 47% 11%;
}
// Component.tsx
<Dialog.Content
className="
bg-[hsl(var(--color-surface))]
rounded-[var(--radius-base)]
shadow-[var(--shadow-lg)]
"
/>
Estrategia 2: Tailwind + CVA (Class Variance Authority)
Mejor para: Proyectos con Tailwind, componentes con muchas variantes
// button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
const buttonVariants = cva(
// Estilos base
"inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/90",
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
outline: "border border-input bg-background hover:bg-accent",
ghost: "hover:bg-accent hover:text-accent-foreground",
},
size: {
default: "h-10 px-4 py-2",
sm: "h-9 rounded-md px-3",
lg: "h-11 rounded-md px-8",
icon: "h-10 w-10",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
}
);
interface ButtonProps extends VariantProps<typeof buttonVariants> {
children: React.ReactNode;
}
export function Button({ variant, size, children }: ButtonProps) {
return (
<button className={cn(buttonVariants({ variant, size }))}>
{children}
</button>
);
}
Estrategia 3: Stitches (CSS-in-JS)
Mejor para: Tematización en tiempo de ejecución, estilos con ámbito
import { styled } from '@stitches/react';
import * as Dialog from '@radix-ui/react-dialog';
const StyledContent = styled(Dialog.Content, {
backgroundColor: '$surface',
borderRadius: '$md',
padding: '$6',
variants: {
size: {
small: { width: '300px' },
medium: { width: '500px' },
large: { width: '700px' },
},
},
defaultVariants: {
size: 'medium',
},
});
Patrones de Componentes
Patrón 1: Componentes Compuestos con Contexto
Caso de uso: Compartir estado entre partes primitivas
// Select.tsx
import * as Select from '@radix-ui/react-select';
import { CheckIcon, ChevronDownIcon } from '@radix-ui/react-icons';
export function SelectorPersonalizado({ items, placeholder, onValueChange }) {
return (
<Select.Root onValueChange={onValueChange}>
<Select.Trigger className="disparador-select">
<Select.Value placeholder={placeholder} />
<Select.Icon>
<ChevronDownIcon />
</Select.Icon>
</Select.Trigger>
<Select.Portal>
<Select.Content className="contenido-select">
<Select.Viewport>
{items.map((item) => (
<Select.Item
key={item.value}
value={item.value}
className="item-select"
>
<Select.ItemText>{item.label}</Select.ItemText>
<Select.ItemIndicator>
<CheckIcon />
</Select.ItemIndicator>
</Select.Item>
))}
</Select.Viewport>
</Select.Content>
</Select.Portal>
</Select.Root>
);
}
Patrón 2: Componentes Polimórficos con asChild
Caso de uso: Renderizar como diferentes elementos sin perder comportamiento
// ✅ Renderizar como un enlace de Next.js pero mantener el comportamiento de Radix
<Dialog.Trigger asChild>
<Link href="/settings">Abrir Configuración</Link>
</Dialog.Trigger>
// ✅ Renderizar como componente personalizado
<DropdownMenu.Item asChild>
<TuBotonPersonalizado icon={<Icon />}>Acción</TuBotonPersonalizado>
</DropdownMenu.Item>
Por qué asChild es importante: Previene problemas de anidamiento de botones/enlaces en el árbol de accesibilidad.
Patrón 3: Controlado vs No Controlado
// No controlado (Radix gestiona el estado)
<Tabs.Root defaultValue="tab1">
<Tabs.Trigger value="tab1">Pestaña 1</Tabs.Trigger>
</Tabs.Root>
// Controlado (Tú gestionas el estado)
const [activeTab, setActiveTab] = useState('tab1');
<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
<Tabs.Trigger value="tab1">Pestaña 1</Tabs.Trigger>
</Tabs.Root>
Regla: Usa controlado cuando necesites sincronizar con estado externo (URL, Redux, etc.).
Patrón 4: Animación con Framer Motion
import * as Dialog from '@radix-ui/react-dialog';
import { motion, AnimatePresence } from 'framer-motion';
export function DialogoAnimado({ open, onOpenChange }) {
return (
<Dialog.Root open={open} onOpenChange={onOpenChange}>
<Dialog.Portal forceMount>
<AnimatePresence>
{open && (
<>
<Dialog.Overlay asChild>
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
className="superposicion-dialogo"
/>
</Dialog.Overlay>
<Dialog.Content asChild>
<motion.div
initial={{ opacity: 0, scale: 0.95 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.95 }}
className="contenido-dialogo"
>
{/* Contenido */}
</motion.div>
</Dialog.Content>
</>
)}
</AnimatePresence>
</Dialog.Portal>
</Dialog.Root>
);
}
Referencia de Primitivas Comunes
Diálogo (Modal)
<Dialog.Root> {/* Contenedor de estado */}
<Dialog.Trigger /> {/* Abre el diálogo */}
<Dialog.Portal> {/* Renderiza en un portal */}
<Dialog.Overlay /> {/* Fondo */}
<Dialog.Content> {/* Contenido del modal */}
<Dialog.Title /> {/* Requerido para accesibilidad */}
<Dialog.Description /> {/* Requerido para accesibilidad */}
<Dialog.Close /> {/* Cierra el diálogo */}
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
Menú Desplegable
<DropdownMenu.Root>
<DropdownMenu.Trigger />
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item />
<DropdownMenu.Separator />
<DropdownMenu.CheckboxItem />
<DropdownMenu.RadioGroup>
<DropdownMenu.RadioItem />
</DropdownMenu.RadioGroup>
<DropdownMenu.Sub> {/* Menús anidados */}
<DropdownMenu.SubTrigger />
<DropdownMenu.SubContent />
</DropdownMenu.Sub>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
Pestañas
<Tabs.Root defaultValue="tab1">
<Tabs.List>
<Tabs.Trigger value="tab1" />
<Tabs.Trigger value="tab2" />
</Tabs.List>
<Tabs.Content value="tab1" />
<Tabs.Content value="tab2" />
</Tabs.Root>
Tooltip
<Tooltip.Provider delayDuration={200}>
<Tooltip.Root>
<Tooltip.Trigger />
<Tooltip.Portal>
<Tooltip.Content side="top" align="center">
Texto del tooltip
<Tooltip.Arrow />
</Tooltip.Content>
</Tooltip.Portal>
</Tooltip.Root>
</Tooltip.Provider>
Popover
<Popover.Root>
<Popover.Trigger />
<Popover.Portal>
<Popover.Content side="bottom" align="start">
Contenido
<Popover.Arrow />
<Popover.Close />
</Popover.Content>
</Popover.Portal>
</Popover.Root>
Lista de Verificación de Accesibilidad
Cada Componente Debe Tener:
- Gestión de Enfoque: Indicadores de enfoque visibles en todos los elementos interactivos
- Navegación por Teclado: Soporte completo de teclado (Tabulador, Flechas, Enter, Esc)
- Etiquetas ARIA: Etiquetas significativas para lectores de pantalla
- Contraste de Color: Mínimo WCAG AA (4.5:1 para texto, 3:1 para UI)
- Estados de Error: Mensajes de error claros con
aria-invalidyaria-describedby - Estados de Carga:
aria-busyadecuado durante operaciones asíncronas
Específico para Diálogos:
-
Dialog.Titleestá presente (requerido para lectores de pantalla) -
Dialog.Descriptionproporciona contexto - El enfoque está atrapado dentro del modal cuando está abierto
- La tecla Escape cierra el diálogo
- El enfoque vuelve al disparador al cerrar
Específico para Menús Desplegables:
- Las flechas navegan entre los elementos
- La búsqueda por escritura funciona
- Comportamiento de envoltura del primer/último elemento
- El estado seleccionado se indica visualmente y con ARIA
Mejores Prácticas
✅ Haz Esto
-
Usa siempre
asChildpara evitar divs envolventes<Dialog.Trigger asChild> <button>Abrir</button> </Dialog.Trigger> -
Proporciona HTML semántico
<Dialog.Content asChild> <article role="dialog" aria-labelledby="title"> {/* contenido */} </article> </Dialog.Content> -
Usa variables CSS para tematización
.dialog-content { background: hsl(var(--surface)); color: hsl(var(--on-surface)); } -
Compón primitivas para componentes complejos
function PaletaDeComandos() { return ( <Dialog.Root> <Dialog.Content> <Combobox /> {/* Combobox de Radix dentro del Diálogo */} </Dialog.Content> </Dialog.Root> ); }
❌ No Hagas Esto
-
No omitas las partes de accesibilidad
// ❌ Faltan Título y Descripción <Dialog.Content> <div>Contenido</div> </Dialog.Content> -
No luches contra las primitivas
// ❌ Sobrescribir el comportamiento interno <Dialog.Content onClick={(e) => e.stopPropagation()}> -
No mezcles controlado y no controlado
// ❌ Gestión de estado inconsistente <Tabs.Root defaultValue="tab1" value={activeTab}> -
No ignores la navegación por teclado
// ❌ Deshabilitar comportamiento del teclado <DropdownMenu.Item onKeyDown={(e) => e.preventDefault()}>
Referencia Rápida de Composición
| Primitiva Base | Componentes Compuestos | Caso de Uso |
|---|---|---|
| Diálogo | Paleta de Comandos, Confirmación, Formulario Modal | Modales, superposiciones |
| Menú Desplegable | Menú de Acciones, Menú de Contexto, Selector | Menús, acciones contextuales |
| Pestañas | Panel de Configuración, Navegación por Pestañas | Alternar vistas, paneles de configuración |
| Tooltip | Ayuda en Línea, Ayuda para Iconos | Información contextual, sugerencias |
| Popover | Menú de Perfil, Selector de Fecha | Superposiciones ligeras, formularios rápidos |
| Select | Selector de Tema, Menú desplegable de Tipo | Selección de opciones, filtros |
| Switch | Alternar Notificaciones, Alternar Modo Oscuro | Alternar binarios, preferencias |
| Slider | Control de Volumen, Control de Rango | Rangos de valores, filtros |
Recursos Relacionados
- Documentación de Radix UI
- Stitches - Biblioteca CSS-in-JS
- Class Variance Authority - Variantes de componentes tipadas
- shadcn/ui - Componentes con estilo construidos sobre Radix
- Guía WCAG 2.1 - Pautas de Accesibilidad al Contenido Web
- Radix UI Colors - Paletas de colores accesibles