¿Qué hace ui?

Un framework para construir UI, componentes y sistemas de diseño. Los componentes se agregan como código fuente al proyecto del usuario a través de la CLI.

IMPORTANTE: Ejecute todos los comandos de la CLI utilizando el gestor de paquetes del proyecto: npx shadcn@latest, pnpm dlx shadcn@latest o bunx --bun shadcn@latest, según el packageManager del proyecto. Los ejemplos a continuación usan npx shadcn@latest, pero sustituya el gestor correcto según el proyecto.

Contexto Actual del Proyecto

!`npx shadcn@latest info --json`

El JSON anterior contiene la configuración del proyecto y los componentes instalados. Use npx shadcn@latest docs <componente> para obtener documentación y URLs de ejemplo para cualquier componente.

Principios

Use componentes existentes primero. Use npx shadcn@latest search para verificar los registros antes de escribir UI personalizada. Revise también los registros de la comunidad.
Componga, no reinvente. Página de configuración = Tabs + Card + controles de formulario. Panel de control = Sidebar + Card + Chart + Table.
Use variantes integradas antes de estilos personalizados. variant="outline", size="sm", etc.
Use colores semánticos. bg-primary, text-muted-foreground: nunca valores brutos como bg-blue-500.

Reglas Críticas

Estas reglas se aplican siempre. Cada una enlaza a un archivo con pares de código Incorrecto/Correcto.

Estilizado y Tailwind → styling.md

className para diseño, no para estilizado. Nunca sobrescriba colores o tipografía de componentes.
No use space-x-* o space-y-*. Use flex con gap-*. Para pilas verticales, flex flex-col gap-*.
Use size-* cuando ancho y alto sean iguales. size-10, no w-10 h-10.
Use el atajo truncate. No overflow-hidden text-ellipsis whitespace-nowrap.
No use sobrescrituras manuales de color dark:. Use tokens semánticos (bg-background, text-muted-foreground).
Use cn() para clases condicionales. No escriba ternarios manuales con literales de plantilla.
No use z-index manual en componentes superpuestos. Dialog, Sheet, Popover, etc. manejan su propia superposición.

Formularios y Entradas → forms.md

Los formularios usan FieldGroup + Field. Nunca use div sin formato con space-y-* o grid gap-* para diseño de formularios.
InputGroup usa InputGroupInput/InputGroupTextarea. Nunca Input/Textarea sin formato dentro de InputGroup.
Los botones dentro de entradas usan InputGroup + InputGroupAddon.
Los conjuntos de opciones (2–7 opciones) usan ToggleGroup. No recorra Button con estado activo manual.
FieldSet + FieldLegend para agrupar checkboxes/radios relacionados. No use un div con un encabezado.
La validación de campos usa data-invalid + aria-invalid. data-invalid en Field, aria-invalid en el control. Para deshabilitado: data-disabled en Field, disabled en el control.

Estructura de Componentes → composition.md

Los elementos siempre están dentro de su Grupo. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
Use asChild (radix) o render (base) para disparadores personalizados. Verifique el campo base de npx shadcn@latest info. → base-vs-radix.md
Dialog, Sheet y Drawer siempre necesitan un Título. Se requiere DialogTitle, SheetTitle, DrawerTitle para accesibilidad. Use className="sr-only" si está oculto visualmente.
Use la composición completa de Card. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. No ponga todo en CardContent.
Button no tiene isPending/isLoading. Componga con Spinner + data-icon + disabled.
TabsTrigger debe estar dentro de TabsList. Nunca renderice disparadores directamente en Tabs.
Avatar siempre necesita AvatarFallback. Para cuando la imagen no se carga.

Use Componentes, No Marcado Personalizado → composition.md

Use componentes existentes antes que marcado personalizado. Verifique si existe un componente antes de escribir un div estilizado.
Los destacados usan Alert. No construya divs estilizados personalizados.
Los estados vacíos usan Empty. No construya marcado de estado vacío personalizado.
Toast sigue la base del proyecto. Use toast del componente toast para proyectos Base UI. Use toast() de sonner para proyectos Radix y React Aria.
Use Separator en lugar de <hr> o <div className="border-t">.
Use Skeleton para marcadores de posición de carga. Sin divs animate-pulse personalizados.
Use Badge en lugar de spans estilizados personalizados.

Iconos → icons.md

Los iconos en Button usan data-icon. data-icon="inline-start" o data-icon="inline-end" en el icono.
No hay clases de tamaño en iconos dentro de componentes. Los componentes manejan el tamaño de los iconos mediante CSS. No use size-4 o w-4 h-4.
Pase iconos como objetos, no como cadenas de texto. icon={CheckIcon}, no una búsqueda por cadena.

Chat y Mensajería → chat.md

La UI de Chat compone los primitivos de chat. Las conversaciones usan MessageScroller, las filas usan Message, las superficies usan Bubble. Nunca divs de burbuja hechos a mano o un contenedor de desplazamiento sin formato.
MessageScroller controla el comportamiento de desplazamiento. El seguimiento de transmisión, el anclaje y el salto al último (MessageScrollerButton) están integrados. No escriba un hook useStickToBottom/ResizeObserver.
Los archivos adjuntos usan Attachment; las notas del sistema y los divisores usan Marker. No tarjetas Item o Separator + una etiqueta.

CLI

Nunca decodifique códigos de preset ni construya URLs de preset manualmente. Use npx shadcn@latest preset decode <código>, preset url <código> o preset open <código>. Para detección de preset con contexto del proyecto, use npx shadcn@latest preset resolve.
Aplique códigos de preset directamente con la CLI. Use npx shadcn@latest apply <código> para proyectos existentes, o npx shadcn@latest init --preset <código> al inicializar.

Patrones Clave

Estos son los patrones más comunes que diferencian el código correcto de shadcn/ui. Para casos extremos, consulte los archivos de reglas enlazados anteriormente.

// Diseño de formulario: FieldGroup + Field, no div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validación: data-invalid en Field, aria-invalid en el control.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Email inválido.</FieldDescription>
</Field>

// Iconos en botones: data-icon, sin clases de tamaño.
<Button>
  <SearchIcon data-icon="inline-start" />
  Buscar
</Button>

// Espaciado: gap-*, no space-y-*.
<div className="flex flex-col gap-4">  // correcto
<div className="space-y-4">           // incorrecto

// Dimensiones iguales: size-*, no w-* h-*.
<Avatar className="size-10">   // correcto
<Avatar className="w-10 h-10"> // incorrecto

// Colores de estado: variantes de Badge o tokens semánticos, no colores brutos.
<Badge variant="secondary">+20.1%</Badge>    // correcto
<span className="text-emerald-600">+20.1%</span> // incorrecto

Selección de Componentes

Necesidad	Use
Botón/Acción	`Button` con la variante adecuada
Entradas de formulario	`Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider`
Alternar entre 2–5 opciones	`ToggleGroup` + `ToggleGroupItem`
Visualización de datos	`Table`, `Card`, `Badge`, `Avatar`
Navegación	`Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`
Superposiciones	`Dialog` (modal), `Sheet` (panel lateral), `Drawer` (hoja inferior), `AlertDialog` (confirmación)
Retroalimentación	`toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner`
Paleta de comandos	`Command` dentro de `Dialog`
Gráficos	`Chart` (envuelve Recharts)
Diseño	`Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`
Estados vacíos	`Empty`
Menús	`DropdownMenu`, `ContextMenu`, `Menubar`
Información/Tooltips	`Tooltip`, `HoverCard`, `Popover`
UI de Chat / Conversación	`MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker`

Campos Clave

El contexto del proyecto inyectado contiene estos campos clave:

aliases → use el prefijo de alias real para las importaciones (por ejemplo, @/, ~/), nunca lo codifique.
isRSC → cuando es true, los componentes que usan useState, useEffect, manejadores de eventos o APIs del navegador necesitan "use client" al inicio del archivo. Siempre haga referencia a este campo al aconsejar sobre la directiva.
tailwindVersion → "v4" usa bloques @theme inline; "v3" usa tailwind.config.js.
tailwindCssFile → el archivo CSS global donde se definen las variables CSS personalizadas. Siempre edite este archivo, nunca cree uno nuevo.
style → tratamiento visual del componente (por ejemplo, nova, vega).
base → librería primitiva (radix o base). Afecta las APIs de los componentes y las props disponibles.
iconLibrary → determina las importaciones de iconos. Use lucide-react para lucide, @tabler/icons-react para tabler, etc. Nunca asuma lucide-react.
resolvedPaths → destinos exactos del sistema de archivos para componentes, utilidades, hooks, etc.
framework → convenciones de enrutamiento y archivos (por ejemplo, Next.js App Router vs Vite SPA).
packageManager → use esto para cualquier instalación de dependencias que no sean de shadcn (por ejemplo, pnpm add date-fns vs npm install date-fns).
preset → código de preset resuelto y valores para el proyecto actual. Use npx shadcn@latest preset resolve --json cuando solo necesite información del preset.

Consulte cli.md — comando info para la referencia completa de campos.

Documentación, Ejemplos y Uso de Componentes

Ejecute npx shadcn@latest docs <componente> para obtener las URLs de la documentación, ejemplos y referencia de API de un componente. Obtenga estas URLs para obtener el contenido real.

npx shadcn@latest docs button dialog select

Al crear, arreglar, depurar o usar un componente, siempre ejecute npx shadcn@latest docs y obtenga las URLs primero. Esto asegura que está trabajando con la API y los patrones de uso correctos, en lugar de adivinar.

Flujo de Trabajo

Obtener contexto del proyecto — ya inyectado arriba. Ejecute npx shadcn@latest info de nuevo si necesita actualizarlo.
Verificar componentes instalados primero — antes de ejecutar add, siempre verifique la lista de components del contexto del proyecto o enumere el directorio resolvedPaths.ui. No importe componentes que no se hayan agregado y no vuelva a agregar los que ya están instalados.
Encontrar componentes — npx shadcn@latest search.
Obtener documentación y ejemplos — ejecute npx shadcn@latest docs <componente> para obtener URLs, luego obténgalas. Use npx shadcn@latest view para explorar elementos del registro que no ha instalado. Para previsualizar cambios en componentes instalados, use npx shadcn@latest add --diff.
Instalar o actualizar — npx shadcn@latest add. Al actualizar componentes existentes, use --dry-run y --diff para previsualizar cambios primero (consulte Actualización de Componentes a continuación).
Arreglar importaciones en componentes de terceros — Después de agregar componentes de registros comunitarios (por ejemplo, @bundui, @magicui), verifique los archivos no UI agregados en busca de rutas de importación codificadas como @/components/ui/.... Estas no coincidirán con los alias reales del proyecto. Use npx shadcn@latest info para obtener el alias ui correcto (por ejemplo, @workspace/ui/components) y reescriba las importaciones en consecuencia. La CLI reescribe las importaciones para sus propios archivos UI, pero los componentes de registro de terceros pueden usar rutas predeterminadas que no coinciden con el proyecto.
Revisar componentes agregados — Después de agregar un componente o bloque de cualquier registro, siempre lea los archivos agregados y verifique que sean correctos. Verifique que no falten subcomponentes (por ejemplo, SelectItem sin SelectGroup), importaciones faltantes, composición incorrecta o violaciones de las Reglas Críticas. También reemplace cualquier importación de iconos con la iconLibrary del proyecto según el contexto del proyecto (por ejemplo, si el elemento del registro usa lucide-react pero el proyecto usa hugeicons, intercambie las importaciones y los nombres de iconos en consecuencia). Corrija todos los problemas antes de continuar.
El registro debe ser explícito — Cuando el usuario solicite agregar un bloque o componente, no adivine el registro. Si no se especifica ningún registro (por ejemplo, el usuario dice "agrega un bloque de inicio de sesión" sin especificar @shadcn, @tailark, owner/repo, etc.), pregunte qué registro usar. Nunca seleccione un registro por defecto en nombre del usuario.
Cambio de presets — Pregunte primero al usuario: ¿sobrescribir, parcial, fusionar u omitir?
- Inspeccionar preset actual: npx shadcn@latest preset resolve. Use --json cuando necesite valores estructurados.
- Inspeccionar preset entrante: npx shadcn@latest preset decode <código>. Use preset url <código> o preset open <código> para compartir o abrir el constructor de presets.
- Sobrescribir: npx shadcn@latest apply <código>. Sobrescribe componentes detectados, fuentes y variables CSS.
- Parcial: npx shadcn@latest apply <código> --only theme,font. Actualiza solo las partes seleccionadas del preset sin reinstalar componentes UI. Los valores admitidos son theme y font; se permiten combinaciones separadas por comas. icon no es compatible intencionalmente, porque los cambios de iconos pueden requerir una reinstalación completa de componentes.
- Fusionar: Aplicación manual. Use npx shadcn@latest apply <código> --diff para previsualizar y mezclar cambios. Use npx shadcn@latest preset diff <código1> <código2> para comparar dos presets.
- Omitir: No hacer nada.

Presets y Personalización

La mayoría de las personalizaciones de shadcn/ui se gestionan a través de presets. Consulte y aplique presets en lugar de editar manualmente variables CSS, fuentes, colores de temas o configuraciones de componentes.

# Comparar configuraciones entre el preset actual y uno nuevo
npx shadcn@latest preset diff

# Ver el preset decodificado con sus valores de configuración
npx shadcn@latest preset decode <código>

# Abrir el constructor de presets usando el código
npx shadcn@latest preset open <código>

Actualización de Componentes

Use --dry-run y --diff para previsualizar cambios antes de aplicar actualizaciones de componentes. Esto es especialmente importante al actualizar componentes instalados existentes (por ejemplo, npx shadcn@latest add button --dry-run --diff).

IMPORTANTE: La opción --all actualiza todos los componentes instalados. Sin embargo, la mayoría de las actualizaciones deberían limitarse al componente o bloque específico que se está modificando. Use --all solo cuando el usuario lo solicite explícitamente.

Diagnóstico y Depuración

Verificación de Componentes Instalados

# Listar todos los componentes instalados
npx shadcn@latest info

# Ver la configuración de un componente específico
npx shadcn@latest info | jq '.components[] | select(.name == "button")'

Verificación de Cambios

# Verificar diferencias entre componentes instalados y el registro
npx shadcn@latest add button --dry-run --diff

Solución de Problemas de Importación

Si los componentes no se importan correctamente:

Verifique el aliases.ui en la configuración del proyecto:

npx shadcn@latest info --json | grep -A 20 '"aliases"'

Verifique que la ruta resuelta exista en el sistema de archivos:

npx shadcn@latest info --json | jq '.resolvedPaths.ui'

Para componentes de registros de terceros, verifique las rutas de importación en los archivos agregados. El CLI reescribe las importaciones para sus propios archivos UI, pero los elementos de registros de terceros pueden usar rutas predeterminadas que no coinciden con los alias del proyecto. Use la información del resolvedPaths.ui del proyecto para corregir estas importaciones manualmente.

Integración con el Sistema de Diseño

Cuando trabaje con un sistema de diseño o una guía de marca:

Primero inspeccione el preset actual: npx shadcn@latest preset resolve
Verifique si existe un preset que coincida con la especificación de diseño. Si existe, use npx shadcn@latest apply <código>.
Si no existe un preset, modele la personalización manualmente. Edite el archivo tailwindCssFile y actualice los valores de los tokens semánticos para que coincidan con la especificación de diseño. No sobrescriba clases nativas de Tailwind.
Documente los cambios de diseño como un preset. Use npx shadcn@latest preset encode para generar un código de preset a partir de la configuración actual del proyecto para compartirlo o reutilizarlo.

shadcn/ui

¿Qué es ui?

Preguntar en tu IA favorita

Documentación