Gestión de shadcn/ui

Exportación de límites de copia y alias de habilidades

La migración, instalación, reparación y reescritura de experiencia solo afectan a la copia de la habilidad objetivo actualmente cargada. La habilidad original de Codex/MCP, el código fuente descargado y original-skills son materiales de origen; no se escribirán debido a la ejecución de esta copia. Solo cuando el usuario solicite explícitamente configurar el producto Codex en sí mismo, se procesará el objetivo especificado de acuerdo con el flujo de ese producto. Cuando el script necesite un directorio de instalación o un directorio de estado, proporcione la ruta de destino explícitamente; no infiera implícitamente la ubicación de escritura desde CODEX_HOME.

Los nombres entre habilidades pueden usar alias del repositorio de origen. Primero consulte la tabla de alias de habilidades, seleccione preferentemente las entradas del mismo origen y complemento, y luego use su id para invocar o leer la entrada correspondiente; no asuma que los nombres antiguos $skill, superpowers:skill están registrados directamente en el nuevo host. Si no puede determinar el objetivo, verifique primero, no reemplace comandos reales del producto o variables de entorno del shell.

Convenciones de uso entre hosts

Esta copia está destinada a clientes que admiten Agent Skills. Primero verifique las herramientas, permisos y servicios conectados realmente proporcionados por el host actual, y luego ejecute el flujo de trabajo del cuerpo. Los identificadores de herramientas del host en el texto original son referencias de capacidad; solo se pueden invocar cuando realmente se encuentra esa herramienta, otros hosts deben usar MCP, CLI o API equivalentes verificados. Los pasos sin capacidades equivalentes deben informarse como no disponibles, no se puede fingir una invocación o estado de finalización.

Los recursos de la habilidad se basan en el directorio de esta habilidad; la salida se escribe en la ubicación especificada por el usuario en el proyecto actual. Se activa por nombre de habilidad o lenguaje natural, los comandos abreviados específicos los determina el host. Los nombres que involucran productos reales, API de modelos, campos de protocolo y URL oficiales mantienen su significado original. Las limitaciones de autorización, aprobación, privacidad y alcance de herramientas siguen vigentes después de la migración; no se pueden ampliar los permisos para lograr compatibilidad. Las dependencias específicas y las instrucciones de migración se encuentran en PORTABILITY.md en el mismo directorio.

shadcn/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 usando el ejecutor 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 ejecutor correcto para el proyecto.

Contexto del Proyecto Actual

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No se encontró un proyecto shadcn. Ejecute shadcn init primero."}'`

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

Principios

1. Use componentes existentes primero. Use npx shadcn@latest search para verificar registros antes de escribir UI personalizada. Verifique también los registros de la comunidad.
2. Componga, no reinvente. Página de configuración = Tabs + Card + controles de formulario. Dashboard = Sidebar + Card + Chart + Table.
3. Use variantes integradas antes que estilos personalizados. variant="outline", size="sm", etc.
4. 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 Incorrecto/Correcto.

Estilos y Tailwind → styling.md

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

Formularios y Entradas → forms.md

• Los formularios usan FieldGroup + Field. Nunca use un div simple con space-y-* o grid gap-* para el diseño del formulario.
• InputGroup usa InputGroupInput/InputGroupTextarea. Nunca Input/Textarea simple 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 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 con estilo.
• Las notificaciones usan Alert. No construya divs personalizados con estilo.
• Los estados vacíos usan Empty. No construya marcado de estado vacío personalizado.
• Toast a través de sonner. Use toast() de sonner.
• Use Separator en lugar de <hr> o <div className="border-t">.
• Use Skeleton para marcadores de posición de carga. Sin divs personalizados con animate-pulse.
• Use Badge en lugar de spans personalizados con estilo.

Iconos → icons.md

• Los iconos en Button usan data-icon. data-icon="inline-start" o data-icon="inline-end" en el icono.
• Sin clases de tamaño en iconos dentro de componentes. Los componentes manejan el tamaño de los iconos a través de CSS. Sin size-4 o w-4 h-4.
• Pase los iconos como objetos, no como claves de cadena. icon={CheckIcon}, no una búsqueda de cadena.

CLI

• Nunca decodifique o busque códigos de preset manualmente. Páselos directamente a npx shadcn@latest init --preset <código>.

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 arriba.

// 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 apropiada
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	sonner (toast), 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/descripciones emergentes	Tooltip, HoverCard, Popover

Campos Clave

El contexto del proyecto inyectado contiene estos campos clave:

• aliases → use el prefijo de alias real para las importaciones (ej. @/, ~/), nunca lo codifique.
• isRSC → cuando es true, los componentes que usan useState, useEffect, manejadores de eventos o APIs del navegador necesitan "use client" en la parte superior 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 (ej. 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 (ej. Next.js App Router vs Vite SPA).
• packageManager → use esto para cualquier instalación de dependencias que no sean de shadcn (ej. pnpm add date-fns vs npm install date-fns).

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 URL de la documentación, ejemplos y referencia de API de un componente. Obtenga estas URL 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 URL primero. Esto asegura que está trabajando con la API y los patrones de uso correctos en lugar de adivinar.

Flujo de Trabajo

1. Obtener contexto del proyecto — ya inyectado arriba. Ejecute npx shadcn@latest info nuevamente si necesita actualizarlo.
2. 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 ya instalados.
3. Encontrar componentes — npx shadcn@latest search.
4. Obtener documentación y ejemplos — ejecute npx shadcn@latest docs <componente> para obtener URL, luego obténgalas. Use npx shadcn@latest view para explorar elementos del registro que no haya instalado. Para previsualizar cambios en componentes instalados, use npx shadcn@latest add --diff.
5. Instalar o actualizar — npx shadcn@latest add. Al actualizar componentes existentes, use --dry-run y --diff para previsualizar los cambios primero (consulte Actualización de Componentes a continuación).
6. Arreglar importaciones en componentes de terceros — Después de agregar componentes de registros de la comunidad (ej. @bundui, @magicui), verifique los archivos no UI agregados para detectar 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 (ej. @workspace/ui/components) y reescriba las importaciones en consecuencia. La CLI reescribe las importaciones para sus propios archivos UI, pero los componentes de registros de terceros pueden usar rutas predeterminadas que no coinciden con el proyecto.
7. 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 si faltan subcomponentes (ej. SelectItem sin SelectGroup), importaciones faltantes, composición incorrecta o violaciones de las Reglas Críticas. También reemplace cualquier importación de iconos con el iconLibrary del proyecto desde el contexto del proyecto (ej. si el elemento del registro usa lucide-react pero el proyecto usa hugeicons, intercambie las importaciones y los nombres de los iconos en consecuencia). Solucione todos los problemas antes de continuar.
8. 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 (ej. el usuario dice "agrega un bloque de inicio de sesión" sin especificar @shadcn, @tailark, etc.), pregunte qué registro usar. Nunca use un registro por defecto en nombre del usuario.
9. Cambio de presets — Pregunte primero al usuario: ¿Reinstalar, fusionar o saltar?
   • Reinstalar: npx shadcn@latest init --preset <código> --force --reinstall. Sobrescribe todos los componentes.
   • Fusionar: npx shadcn@latest init --preset <código> --force --no-reinstall, luego ejecute npx shadcn@latest info para listar los componentes instalados, luego para cada componente instalado use --dry-run y --diff para fusionar inteligentemente individualmente.
   • Saltar: npx shadcn@latest init --preset <código> --force --no-reinstall. Solo actualiza la configuración y CSS, deja los componentes como están.
   • Importante: Siempre ejecute los comandos de preset dentro del directorio del proyecto del usuario. La CLI preserva automáticamente la base actual (base vs radix) de components.json. Si debe usar un directorio temporal (ej. para comparaciones --dry-run), pase --base <base-actual> explícitamente — los códigos de preset no codifican la base.

Actualización de Componentes

Cuando el usuario solicite actualizar un componente desde el upstream mientras mantiene sus cambios locales, use --dry-run y --diff para fusionar inteligentemente. NUNCA obtenga el archivo raw directamente — el CLI maneja correctamente las fusiones.

# Vista previa de los cambios
npx shadcn@latest add button --dry-run --diff

# Aplicar la actualización (fusiona los cambios locales con los del upstream)
npx shadcn@latest add button

NUNCA use --overwrite a menos que el usuario solicite explícitamente sobrescribir sus cambios locales. --overwrite descartará todas las modificaciones locales.

Base vs Radix

El campo base en el contexto del proyecto determina qué librería de componentes primitivos usa el proyecto:

Característica	radix	base
asChild	Sí	No — use render
render prop	No	Sí — para contenido personalizado
Composición	Anidación estricta de componentes	Más flexible

Verifique isRSC y base en el contexto del proyecto para determinar qué API usar. Consulte base-vs-radix.md para ejemplos detallados.

Referencia de Registros"