Patrones ShadCN UI - Estándares de Noviembre 2025
Cuándo Usarlo
- Construir nuevos componentes de interfaz de usuario
- Refactorizar componentes existentes para usar ShadCN
- Implementar formularios con validación
- Crear modales, diálogos y superposiciones
- Garantizar el cumplimiento de accesibilidad
¿Por Qué ShadCN UI?
- Copiar y pegar, no npm: Propiedad completa del código del componente
- Primitivas Radix UI: Accesibilidad integrada (WCAG 2.1 AA)
- Primero TailwindCSS: Personalización completa, sin CSS-in-JS
- Nativo TypeScript: Props y variantes con seguridad de tipos
- Compatible con Componentes del Servidor: Funciona con Next.js 15 App Router
Principios Básicos
1. Patrón de Instalación de Componentes
# Instalar componentes individualmente según sea necesario
npx shadcn@latest add button
npx shadcn@latest add dialog
npx shadcn@latest add form
npx shadcn@latest add input
npx shadcn@latest add label
Los componentes se copian al directorio src/components/ui/ – tú eres dueño del código.
2. Patrones de Uso de Componentes
Componente Button
import { Button } from "@/components/ui/button"
// ✅ HACER: Usar variantes semánticas
<Button variant="default">Guardar</Button>
<Button variant="destructive">Eliminar</Button>
<Button variant="outline">Cancelar</Button>
<Button variant="ghost">Saltar</Button>
<Button variant="link">Más Información</Button>
// ✅ HACER: Usar variantes de tamaño
<Button size="default">Mediano</Button>
<Button size="sm">Pequeño</Button>
<Button size="lg">Grande</Button>
<Button size="icon"><Icon /></Button>
// ❌ NO HACER: Crear botones personalizados sin usar el componente Button
<button className="px-4 py-2 bg-blue-500">Malo</button>
Componente Dialog/Modal
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog"
// ✅ HACER: Usar la estructura adecuada del diálogo (accesibilidad)
<Dialog>
<DialogTrigger asChild>
<Button>Abrir Configuración</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Configuración</DialogTitle>
<DialogDescription>
Configura aquí los ajustes de tu aplicación.
</DialogDescription>
</DialogHeader>
{/* Contenido del diálogo */}
</DialogContent>
</Dialog>
// ❌ NO HACER: Omitir DialogHeader o DialogTitle (rompe lectores de pantalla)
<DialogContent>
<h2>Configuración</h2> {/* Incorrecto - usa DialogTitle */}
</DialogContent>
Componente Form (con React Hook Form + Zod)
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import {
Form,
FormControl,
FormDescription,
FormField,
FormItem,
FormLabel,
FormMessage,
} from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"
// ✅ HACER: Definir el esquema Zod primero (validación)
const formSchema = z.object({
email: z.string().email("Dirección de correo no válida"),
password: z.string().min(8, "La contraseña debe tener al menos 8 caracteres"),
})
function LoginForm() {
const form = useForm<z.infer<typeof formSchema>>({
resolver: zodResolver(formSchema),
defaultValues: {
email: "",
password: "",
},
})
async function onSubmit(values: z.infer<typeof formSchema>) {
// Datos validados con seguridad de tipos
console.log(values)
}
return (
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
<FormField
control={form.control}
name="email"
render={({ field }) => (
<FormItem>
<FormLabel>Correo Electrónico</FormLabel>
<FormControl>
<Input placeholder="[email protected]" {...field} />
</FormControl>
<FormDescription>
Nunca compartiremos tu correo.
</FormDescription>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name="password"
render={({ field }) => (
<FormItem>
<FormLabel>Contraseña</FormLabel>
<FormControl>
<Input type="password" {...field} />
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<Button type="submit">Iniciar Sesión</Button>
</form>
</Form>
)
}
// ❌ NO HACER: Usar formularios no controlados sin validación
<form>
<input name="email" /> {/* Sin validación */}
</form>
3. Componentes del Servidor vs. del Cliente
// ✅ HACER: Usar Componente del Servidor para diálogos estáticos
import { Dialog, DialogContent } from "@/components/ui/dialog"
export default function ServerDialog() {
// No necesita 'use client'
return <Dialog>...</Dialog>
}
// ✅ HACER: Usar Componente del Cliente cuando se necesita estado
'use client'
import { useState } from 'react'
import { Dialog, DialogContent } from "@/components/ui/dialog"
export function ClientDialog() {
const [open, setOpen] = useState(false)
return (
<Dialog open={open} onOpenChange={setOpen}>
<DialogContent>...</DialogContent>
</Dialog>
)
}
4. Requisitos de Accesibilidad
Gestión del Enfoque
// ✅ HACER: Usar DialogTrigger con asChild para un enfoque adecuado
<DialogTrigger asChild>
<Button>Abrir</Button>
</DialogTrigger>
// ❌ NO HACER: Activar manualmente sin un manejo adecuado del enfoque
<Button onClick={() => setOpen(true)}>Abrir</Button>
Navegación por Teclado
// ✅ ShadCN maneja esto automáticamente:
// - ESC cierra los diálogos
// - Tab navega entre elementos enfocables
// - Enter/Espacio activa botones
// - Flechas navegan por menús
// ❌ NO HACER: Sobrescribir el comportamiento predeterminado del teclado sin una buena razón
Soporte para Lectores de Pantalla
// ✅ HACER: Incluir siempre DialogTitle (obligatorio para ARIA)
<DialogHeader>
<DialogTitle>Eliminar Proyecto</DialogTitle>
<DialogDescription>
Esta acción no se puede deshacer.
</DialogDescription>
</DialogHeader>
// ❌ NO HACER: Usar títulos ocultos visualmente de forma incorrecta
<DialogTitle className="sr-only">Eliminar</DialogTitle>
// Solo ocultar si existe una alternativa visual clara
5. Componentes Comunes a Usar
| Componente | Caso de Uso | Props Clave |
|---|---|---|
Button | Todas las acciones clickeables | variant, size, asChild |
Dialog | Modales, confirmaciones | open, onOpenChange |
Sheet | Paneles laterales, cajones | side, open, onOpenChange |
Popover | Tooltips, menús | open, onOpenChange |
Form | Todos los formularios | form (de useForm) |
Input | Entrada de texto | type, placeholder |
Select | Desplegables | value, onValueChange |
Checkbox | Entrada booleana | checked, onCheckedChange |
RadioGroup | Selección única | value, onValueChange |
Table | Tablas de datos | table (de TanStack Table) |
Card | Contenedores de contenido | CardHeader, CardContent, CardFooter |
Toast | Notificaciones | title, description, variant |
Command | Paleta de comandos | onSelect |
Tabs | Navegación por pestañas | value, onValueChange |
6. Mejores Prácticas de TailwindCSS
// ✅ HACER: Usar clases utilitarias de Tailwind
<Button className="w-full mt-4">Enviar</Button>
// ✅ HACER: Usar el helper cn() para clases condicionales
import { cn } from "@/lib/utils"
<Button className={cn(
"w-full",
isLoading && "opacity-50 cursor-not-allowed"
)}>
Enviar
</Button>
// ❌ NO HACER: Usar estilos en línea
<Button style={{ width: '100%', marginTop: '16px' }}>Enviar</Button>
// ❌ NO HACER: Crear archivos CSS personalizados para componentes
// styles.css
.my-button { width: 100%; }
7. Soporte para Modo Oscuro
// ✅ HACER: Usar clases de modo oscuro de Tailwind
<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
Contenido
</div>
// ✅ Los componentes ShadCN tienen modo oscuro incorporado
<Button variant="default">
{/* Estilizado automáticamente para modo oscuro */}
</Button>
Errores Comunes a Detectar
❌ Falta de DialogTitle (Violación de Accesibilidad)
// MALO
<DialogContent>
<h2>Configuración</h2>
<p>Contenido</p>
</DialogContent>
// BUENO
<DialogContent>
<DialogHeader>
<DialogTitle>Configuración</DialogTitle>
</DialogHeader>
<p>Contenido</p>
</DialogContent>
❌ No Usar el Componente Form para Formularios
// MALO - Sin validación, mala experiencia de usuario
<form>
<input name="email" />
<button type="submit">Enviar</button>
</form>
// BUENO - Validación, mensajes de error, accesibilidad
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)}>
<FormField name="email" ... />
</form>
</Form>
❌ Codificar Colores en Lugar de Usar Variantes
// MALO
<Button className="bg-red-500 hover:bg-red-600">Eliminar</Button>
// BUENO
<Button variant="destructive">Eliminar</Button>
❌ No Usar asChild para los Disparadores
// MALO - Crea botones anidados innecesarios
<DialogTrigger>
<Button>Abrir</Button>
</DialogTrigger>
// Renderiza: <button><button>Abrir</button></button> (HTML no válido)
// BUENO - Fusiona props en un solo botón
<DialogTrigger asChild>
<Button>Abrir</Button>
</DialogTrigger>
// Renderiza: <button>Abrir</button>
Pruebas de Componentes ShadCN
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { Dialog, DialogTrigger, DialogContent } from '@/components/ui/dialog'
describe('Dialog', () => {
it('debe abrirse cuando se hace clic en el disparador', async () => {
const user = userEvent.setup()
render(
<Dialog>
<DialogTrigger asChild>
<button>Abrir</button>
</DialogTrigger>
<DialogContent>
<div>Contenido del diálogo</div>
</DialogContent>
</Dialog>
)
// El contenido del diálogo no debe ser visible inicialmente
expect(screen.queryByText('Contenido del diálogo')).not.toBeInTheDocument()
// Hacer clic en el disparador
await user.click(screen.getByText('Abrir'))
// El contenido del diálogo ahora debe ser visible
expect(screen.getByText('Contenido del diálogo')).toBeInTheDocument()
})
it('debe cerrarse con la tecla ESC', async () => {
const user = userEvent.setup()
render(
<Dialog defaultOpen>
<DialogContent>Contenido del diálogo</DialogContent>
</Dialog>
)
expect(screen.getByText('Contenido del diálogo')).toBeInTheDocument()
await user.keyboard('{Escape}')
expect(screen.queryByText('Contenido del diálogo')).not.toBeInTheDocument()
})
})
Recursos
- Documentación Oficial: https://ui.shadcn.com
- Radix UI: https://www.radix-ui.com
- Ejemplos: https://ui.shadcn.com/examples
- Temas: https://ui.shadcn.com/themes
Nota de Noviembre 2025
ShadCN UI es el estándar de la industria para librerías de componentes React a partir de noviembre de 2025. Todas las nuevas aplicaciones Quetrex deben usar ShadCN UI para garantizar consistencia, accesibilidad y mantenibilidad.