shadcn

Visión general de la skill shadcn

Para qué sirve la skill shadcn

La skill shadcn ayuda a un asistente de IA a trabajar correctamente dentro de proyectos reales con shadcn/ui: localizar componentes, instalarlos con el CLI adecuado, componer pantallas a partir de primitivas existentes y evitar errores habituales de API entre presets y familias de componentes. Resulta especialmente útil cuando necesitas algo más que “genera un botón” y buscas una salida que respete components.json, los elementos del registry que ya tienes instalados, tu plantilla y las diferencias entre base y radix.

Quién debería usar esta skill shadcn

Encaja mejor para:

• desarrolladores que ya usan shadcn/ui
• equipos que están adoptando un preset o un flujo de UI basado en registry
• personas que piden a la IA añadir o refactorizar formularios, diálogos, páginas de ajustes, dashboards o trabajo de temas
• cualquiera que quiera que el asistente inspeccione el contexto del proyecto antes de escribir JSX

Si no usas shadcn/ui, components.json o el CLI de shadcn, esta skill probablemente sea demasiado específica.

El trabajo real que resuelve

Los usuarios no solo quieren un resumen del repositorio. Quieren que el asistente:

1. detecte la configuración shadcn del proyecto,
2. elija componentes existentes antes de inventar otros nuevos,
3. use los comandos CLI correctos y los flags documentados,
4. componga la UI siguiendo los patrones preferidos de la librería,
5. evite fallos sutiles como una composición incorrecta de triggers, wrappers de grupo ausentes o una integración errónea de la validación en formularios.

Ahí es donde esta skill shadcn aporta valor frente a un prompt de UI genérico.

Qué diferencia a shadcn de un prompt genérico

Los factores diferenciales más sólidos son prácticos:

• parte del contexto del proyecto con npx shadcn@latest info --json
• prioriza search, view y docs antes de cualquier implementación personalizada
• incorpora reglas del proyecto desde archivos como rules/composition.md, rules/forms.md, rules/styling.md y rules/base-vs-radix.md
• cubre theming y cambio de presets, no solo snippets de componentes
• incluye pautas de MCP para flujos de búsqueda e instalación en registries

En resumen, la skill shadcn trata menos de “escribe React” y más de “escribe el React correcto para esta configuración de shadcn”.

Restricciones importantes de adopción

Antes de apoyarte en esta skill, ten en cuenta estas restricciones:

• asume acceso al CLI de shadcn mediante el ejecutor de paquetes del proyecto: npx, pnpm dlx o bunx --bun
• está limitada a los flags documentados del CLI; la skill advierte explícitamente que no se inventen flags
• muchas buenas respuestas dependen de un components.json válido
• los detalles de la API pueden variar según el preset y según base vs radix, así que reutilizar ejemplos a ciegas puede dar resultados incorrectos

Cómo usar la skill shadcn

Contexto de instalación para la skill shadcn

Añade la skill a tu entorno de IA con el flujo de instalación estándar del directorio y úsala dentro de un repositorio que realmente tenga, o vaya a tener, una configuración de shadcn. En la práctica, el requisito del lado del repositorio importa más que el comando de instalación de la skill: el asistente necesita acceso a los archivos de tu proyecto y debería poder ejecutar comandos del CLI de shadcn.

Dentro del proyecto de destino, los comandos de ejecución relevantes son:

• npx shadcn@latest info --json
• npx shadcn@latest search <query>
• npx shadcn@latest view <item>
• npx shadcn@latest docs <component>
• npx shadcn@latest add <component>

Sustituye por pnpm dlx shadcn@latest o bunx --bun shadcn@latest si encaja mejor con el gestor de paquetes del proyecto.

Lee primero estos archivos antes de pedir resultados

Para usar shadcn con rapidez y precisión, conviene revisar estos archivos aproximadamente en este orden:

1. SKILL.md
2. cli.md
3. rules/composition.md
4. rules/base-vs-radix.md
5. rules/forms.md
6. rules/styling.md
7. customization.md
8. mcp.md

Por qué este orden funciona:

• SKILL.md define las condiciones de activación y el flujo de trabajo
• cli.md evita comandos y flags inventados
• los archivos de rules/ recogen errores que la generación de código genérica suele cometer
• customization.md importa cuando necesitas estilos seguros para el tema, no hacks de color directos con Tailwind
• mcp.md importa cuando tu asistente puede explorar registries vía MCP en lugar de depender del shell

Empieza cada tarea de shadcn con descubrimiento del proyecto

El mejor primer paso, casi siempre, es:

npx shadcn@latest info --json

Esto le indica al asistente qué está ya configurado, incluido el contexto de componentes y del proyecto. Es especialmente útil para:

• comprobar si existe components.json
• identificar qué componentes están instalados
• detectar detalles de configuración que cambian qué código es válido
• confirmar el ejecutor de paquetes y evitar ejemplos de comandos incorrectos

Si te saltas este paso, la skill shadcn se parece mucho más a un prompt genérico.

Convierte un objetivo difuso en un buen prompt para shadcn

Prompt débil:

Build me a profile dialog with shadcn.

Mejor prompt:

In this existing shadcn/ui app, inspect components.json and run npx shadcn@latest info --json first. We use the radix setup and lucide-react. Create a profile edit dialog using existing shadcn components only where possible. Include avatar, name, bio, Save/Cancel actions, accessible title, semantic tokens, and no raw color classes. If a component is missing, tell me the exact shadcn add command before generating code.

Por qué este prompt es mejor:

• obliga a descubrir primero el proyecto
• especifica comportamientos sensibles al preset
• deja claras las restricciones de iconos y estilos
• pide pasos de instalación si faltan dependencias

Usa search y docs antes de escribir código personalizado

Un flujo de trabajo de calidad con shadcn suele ser:

1. buscar componentes existentes en los registries,
2. revisar la documentación y los ejemplos,
3. añadir las piezas que falten,
4. componer la pantalla.

Comandos prácticos:

npx shadcn@latest search dialog
npx shadcn@latest docs dialog
npx shadcn@latest view @shadcn/dialog

Esto es especialmente importante en formularios, overlays, navegación y empty states, donde las reglas de la skill priorizan los patrones de la librería frente a estructuras improvisadas con div.

Compón pantallas a partir de bloques existentes

La skill shadcn da su mejor resultado cuando le pides composición, no una UI monolítica hecha a medida. Buenas formas de plantear una tarea:

• “settings page = Tabs + Card + form controls”
• “dashboard = Sidebar + Card + Chart + Table”
• “empty state = Empty component, not a custom centered div”
• “callout = Alert, not hand-rolled border boxes”

Esto refleja el flujo preferido de la skill: usar primero componentes existentes y adaptar variantes y wrappers solo cuando haga falta.

Respeta las diferencias entre base y radix

Uno de los mayores bloqueos al adoptar shadcn es asumir que todos los ejemplos son intercambiables. No lo son.

La skill incluye indicaciones explícitas para base vs radix, entre ellas:

• asChild vs render
• diferencias en la composición de triggers
• nativeButton={false} en casos concretos exclusivos de base
• diferencias de API en componentes como Select, ToggleGroup, Slider y Accordion

Si tu prompt no dice qué configuración usas, pídele al asistente que la detecte a partir de npx shadcn@latest info.

Usa pautas de estilos que sobrevivan al theming

En shadcn for UI Design, los mejores resultados vienen de tokens semánticos y theming basado en variables CSS, no de colores Tailwind codificados a mano.

Prioriza:

• bg-background
• text-foreground
• text-muted-foreground
• text-destructive

Evita usar por defecto:

• bg-red-500
• text-gray-400
• demasiados overrides manuales con dark:

Esto importa porque customization.md explica que los componentes heredan de variables CSS. Si el asistente usa tokens semánticos, tu diseño escala mucho mejor entre temas claros/oscursos y distintos presets.

Gestiona los formularios a la manera de shadcn

Las evaluaciones y reglas dejan claro que la calidad de los formularios es un foco importante. Un uso sólido de shadcn en formularios suele implicar:

• usar los patrones de layout de campos proporcionados en lugar de apilar divs sin más
• marcar el estado inválido con data-invalid y aria-invalid
• usar Switch para preferencias independientes de encendido/apagado
• preferir espaciado con gap-* frente a space-y-* cuando así lo indiquen las reglas

Si tu tarea incluye validación, dilo de forma explícita. Si no, muchos asistentes generan formularios visualmente convincentes pero inconsistentes con la librería.

Usa MCP si tu editor lo admite

Si tu entorno admite MCP, la skill shadcn puede ser más fiable en operaciones de registry. mcp.md documenta herramientas para:

• listar los registries del proyecto
• buscar elementos en el registry
• ver detalles de los elementos y el contenido de sus archivos
• obtener ejemplos
• instalar elementos

Esto resulta útil cuando quieres que el asistente explore registries de forma conversacional en lugar de apoyarse solo en la salida del CLI. No sustituye a info --json para la configuración del proyecto.

Plantilla práctica de prompt para usar shadcn

Usa esta plantilla cuando quieras resultados de mayor calidad:

Use the shadcn skill for this task. First inspect the project with `npx shadcn@latest info --json` and read `components.json` if present. Confirm whether this project uses `base` or `radix`. Search for existing components before building custom UI. If something is missing, give the exact documented `shadcn add` command. Then generate the component using semantic tokens, correct composition rules, and the project’s icon library.

Goal: [what you want to build]
Screen context: [page/dialog/form/dashboard/etc.]
Existing components: [if known]
Framework/template: [Next.js/Vite/Astro/etc.]
Constraints: [icons, validation, dark mode, accessibility, no raw colors, no guessed APIs]
Output needed: [component code, install commands, explanation, refactor diff]

Preguntas frecuentes sobre la skill shadcn

¿Esta skill shadcn solo sirve para instalar componentes?

No. Las tareas de shadcn install forman parte de su alcance, pero la skill es más amplia: inspección del proyecto, búsqueda en registries, composición de componentes, theming, depuración, cambio de presets y refactors correctos a nivel de API también entran dentro de su uso.

¿La skill shadcn es apta para principiantes?

Sí, si ya te manejas con React y con un gestor de paquetes. La skill reduce las conjeturas porque orienta al asistente hacia los comandos y reglas correctos. Es menos amigable para principiantes si necesitas una introducción completa a React, Tailwind o sistemas de diseño desde cero.

¿Cuándo conviene más shadcn que un prompt normal?

Usa la skill shadcn cuando la corrección dependa del contexto del proyecto:

• un components.json existente
• componentes instalados que hay que respetar
• comportamiento base vs radix
• uso exclusivo de flags CLI documentados
• conservación de tokens de tema y reglas de composición de la librería

Un prompt normal puede generar JSX plausible, pero es más probable que omita pasos de instalación o use mal las APIs de los componentes.

¿Cuándo no deberías usar la skill shadcn?

Sáltatela si:

• tu proyecto no usa shadcn/ui
• solo necesitas mockups genéricos en HTML/CSS
• quieres una respuesta agnóstica respecto al sistema de diseño
• el asistente no puede inspeccionar archivos ni ejecutar comandos, y tú tampoco puedes aportar manualmente el contexto necesario

En esos casos, una skill frontend más amplia puede encajar mejor.

¿La skill ayuda con decisiones de shadcn for UI Design?

Sí, especialmente en composición y theming. Empuja al asistente hacia primitivas reutilizables, tokens semánticos de color, patrones correctos de overlays y estructuras de componentes más fáciles de mantener que layouts artesanales de un solo uso.

¿Qué es lo que más suele romper el uso de shadcn en salidas de IA?

Los fallos más comunes incluyen:

• inventar flags CLI no soportados
• usar una composición de triggers incorrecta para base vs radix
• crear UI personalizada en vez de usar un componente existente del registry
• aplicar estilos con colores directos que chocan con el sistema de temas
• omitir subcomponentes obligatorios como titles, groups o fallbacks

Precisamente esas son las áreas que esta skill busca ajustar mejor.

Cómo mejorar la skill shadcn

Dale a la skill shadcn el contexto que falta desde el principio

La mejora con más impacto suele estar en la entrada, no en la salida. Incluye:

• framework o plantilla (next, vite, astro, etc.)
• si existe components.json
• base o radix si ya lo sabes
• set actual de iconos
• componente o pantalla objetivo
• si la tarea incluye instalación, refactor o corrección de errores

Incluso una sola frase con contexto concreto puede evitar que el asistente elija APIs equivocadas.

Pide comandos antes que código cuando puedan faltar componentes

Si existe la posibilidad de que tu proyecto no tenga instalado el componente necesario, usa un prompt como este:

Before writing code, check whether the required shadcn components are already present. If not, give me the exact add command and wait.

Esto mejora el resultado porque separa los cambios de entorno de la implementación, y hace que sea más fácil confiar en la respuesta y aplicarla.

Fuerza una salida consciente de las reglas en componentes frágiles

Para formularios, diálogos, dropdowns, sheets, drawers y selects, pide explícitamente al asistente que siga los archivos de reglas. Ejemplo:

Follow the shadcn rules for composition, forms, and base-vs-radix differences. Do not simplify structure if it changes the component API.

Esto importa porque muchas generaciones flojas parecen correctas a simple vista, pero rompen contratos de accesibilidad o de composición.

Mejora el uso de shadcn especificando restricciones de diseño

Un buen prompt de UI no es solo “hazlo moderno”. Incluye restricciones como:

• solo tokens semánticos
• sin utilidades de paleta en bruto
• el modo oscuro debe funcionar sin overrides manuales
• usar variantes existentes antes que clases personalizadas
• priorizar empty states, alerts, separators, badges y skeletons de la librería

Estos detalles mejoran de forma tangible la calidad del primer intento en trabajos de shadcn for UI Design.

Itera con correcciones concretas, no con reescrituras completas

Después de la primera salida, evita decir solo “inténtalo de nuevo”. Mejor di:

• “Refactor this to use installed shadcn components only.”
• “Make this valid for base, not radix.”
• “Replace raw color classes with semantic tokens.”
• “Add the missing title/fallback/group wrappers required by shadcn.”
• “Show the exact shadcn add commands for anything assumed.”

Así conservas lo que ya está bien y corriges justo las partes con más probabilidades de estar mal.

Valida la salida frente a las señales más fuertes del repositorio

Para mejorar la confianza, compara la salida con:

• cli.md para comandos y flags
• rules/composition.md para estructura
• rules/base-vs-radix.md para corrección de API
• rules/forms.md para patrones de validación y layout
• rules/styling.md y customization.md para estilos seguros con el tema
• evals/evals.json para ver cómo es una buena salida en la práctica

Esa es la forma más rápida de comprobar si la skill shadcn está generando una respuesta alineada con el repositorio y no código de UI genérico.