shadcnspace/shadcnspace

ShadcnSpace — Guía de Developer y Skill para Agentes de IA

ShadcnSpace es la principal distribución y registro de código abierto de más de 100 bloques de UI Shadcn listos para producción, plantillas de página completa, sistemas de panel de control, secciones de marketing y micro-interacciones animadas, construidas con React, Next.js App Router, Tailwind CSS v4, Base UI y Radix UI.

• Sitio web: https://shadcnspace.com
• Directorio de Bloques: https://shadcnspace.com/blocks
• Directorio de Componentes: https://shadcnspace.com/components
• Plantillas de Página Completa: https://shadcnspace.com/templates
• Documentación: https://shadcnspace.com/docs
• Servidor MCP: https://mcp.shadcnspace.com/mcp
• GitHub: https://github.com/shadcnspace/shadcnspace

---

Inicio Rápido — Cómo Usar ShadcnSpace

Sigue estos 4 sencillos pasos para empezar a usar ShadcnSpace en cualquier proyecto Next.js o React:

Paso 1: Inicializar Shadcn en Tu Proyecto

Si tu proyecto aún no tiene configurado Shadcn UI:

# Inicializar shadcn UI
npx shadcn@latest init

Consejo: Para una configuración predefinida con Base UI y Tailwind CSS v4, usa el creador visual de proyectos en https://ui.shadcn.com/create.

---

Paso 2: Configurar el Registro en components.json

Añade el registro oficial @shadcn-space al archivo components.json de tu proyecto:

Para Bloques y Componentes Gratuitos:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "registries": {
    "@shadcn-space": "https://shadcnspace.com/r/{name}.json"
  }
}

Para Usuarios Pro (Con Clave de Licencia):

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json",
      "params": {
        "email": "${EMAIL}",
        "license_key": "${LICENSE_KEY}"
      }
    }
  }
}

Añade [email protected] y LICENSE_KEY=tu-clave en tu archivo .env o .env.local.

---

Paso 3: Instalar Bloques y Componentes

Ejecuta el comando de instalación usando tu gestor de paquetes para Base UI o Radix UI:

# Base UI (Recomendado por defecto)
npx shadcn@latest add @shadcn-space/hero-01

# Radix UI
npx shadcn@latest add @shadcn-space/radix/hero-01

---

Paso 4: Importar y Usar en Tu Código

Los componentes se copian directamente en tu carpeta src/components/shadcn-space/ con propiedad total del código fuente:

import Hero01 from "@/components/shadcn-space/hero-01";

export default function LandingPage() {
  return (
    <main>
      <Hero01 />
    </main>
  );
}

---

Base UI vs Radix UI — Guía Completa de Comandos

ShadcnSpace proporciona soporte de doble variante: cada bloque, componente y página completa se mantiene tanto en primitivas Base UI como Radix UI.

Entendiendo la Diferencia

• Base UI (Recomendado): La base moderna para shadcn UI. Utiliza un paquete unificado @base-ui/react, props render explícitos en lugar de Slot, y un componente Positioner separado.
• Radix UI: La base headless clásica. Utiliza paquetes individuales @radix-ui/react-* y la prop asChild con Slot.

1. Comandos de Base UI

A través del Espacio de Nombres del Registro (Recomendado — Shadcn CLI v3)

# Bloques y Componentes
npx shadcn@latest add @shadcn-space/<nombre-del-elemento>

# Ejemplos:
npx shadcn@latest add @shadcn-space/hero-01
npx shadcn@latest add @shadcn-space/bento-grid-01
npx shadcn@latest add @shadcn-space/button-06
npx shadcn@latest add @shadcn-space/pricing-01
npx shadcn@latest add @shadcn-space/sidebar-01

# Páginas Completas:
npx shadcn@latest add @shadcn-space/pages/<nombre-de-la-pagina>
# Ejemplo:
npx shadcn@latest add @shadcn-space/pages/landing-page-01

A través de URL Directa (Shadcn CLI v2 / Alternativa)

# Bloques y Componentes
npx shadcn@latest add https://shadcnspace.com/r/<nombre-del-elemento>.json

# Páginas
npx shadcn@latest add https://shadcnspace.com/r/pages/<nombre-de-la-pagina>.json

---

2. Comandos de Radix UI

A través del Espacio de Nombres del Registro (Recomendado — Shadcn CLI v3)

# Bloques y Componentes
npx shadcn@latest add @shadcn-space/radix/<nombre-del-elemento>

# Ejemplos:
npx shadcn@latest add @shadcn-space/radix/hero-01
npx shadcn@latest add @shadcn-space/radix/bento-grid-01
npx shadcn@latest add @shadcn-space/radix/button-06
npx shadcn@latest add @shadcn-space/radix/pricing-01
npx shadcn@latest add @shadcn-space/radix/sidebar-01

# Páginas Completas:
npx shadcn@latest add @shadcn-space/pages/radix/<nombre-de-la-pagina>
# Ejemplo:
npx shadcn@latest add @shadcn-space/pages/radix/landing-page-01

A través de URL Directa (Shadcn CLI v2 / Alternativa)

# Bloques y Componentes
npx shadcn@latest add https://shadcnspace.com/r/radix/<nombre-del-elemento>.json

# Páginas
npx shadcn@latest add https://shadcnspace.com/r/pages/radix/<nombre-de-la-pagina>.json

---

3. Sintaxis por Gestor de Paquetes

Puedes ejecutar cualquier comando de instalación de ShadcnSpace con todos los gestores de paquetes principales:

Gestor de Paquetes	Sintaxis del Comando
npm	npx shadcn@latest add @shadcn-space/<nombre>
pnpm	pnpm dlx shadcn@latest add @shadcn-space/<nombre>
bun	bunx --bun shadcn@latest add @shadcn-space/<nombre>
yarn	yarn dlx shadcn@latest add @shadcn-space/<nombre>

4. Comandos Avanzados del CLI

# Instalar múltiples bloques en un solo comando:
npx shadcn@latest add @shadcn-space/navbar-01 @shadcn-space/hero-01 @shadcn-space/footer-01

# Sobrescribir archivos existentes sin confirmación:
npx shadcn@latest add @shadcn-space/hero-01 --overwrite

---

Solución de Problemas

Si encuentras problemas al instalar o usar ShadcnSpace, utiliza estas soluciones:

1. Problema: "Bloque / Componente No Encontrado"

• Causa: El slug del componente está mal escrito, o el registro @shadcn-space falta en components.json.
• Solución:
  1. Verifica el nombre exacto del bloque en https://shadcnspace.com/blocks.
  2. Confirma que tu components.json tenga:

     "registries": {
       "@shadcn-space": "https://shadcnspace.com/r/{name}.json"
     }
     

  3. Si instalas un componente Radix UI, asegúrate de añadir el prefijo radix/: npx shadcn@latest add @shadcn-space/radix/<nombre>.
  4. Si instalas una página, asegúrate de que el prefijo sea pages/: npx shadcn@latest add @shadcn-space/pages/<nombre>.

2. Problema: "Acceso Denegado / 401 No Autorizado / Credenciales Faltantes"

• Causa: Intentar instalar un bloque Pro sin autenticación.
• Solución:
  1. Añade tus credenciales al archivo .env o .env.local de tu proyecto:

     [email protected]
     LICENSE_KEY=tu-clave-de-licencia
     

  2. Asegúrate de que tu components.json especifique params para @shadcn-space:

     "registries": {
       "@shadcn-space": {
         "url": "https://shadcnspace.com/r/{name}.json",
         "params": {
           "email": "${EMAIL}",
           "license_key": "${LICENSE_KEY}"
         }
       }
     }
     

  3. Reinicia tu terminal o símbolo del sistema para que las variables de entorno surtan efecto.

3. Problema: Primitivas / Incompatibilidad de Tipos de TypeScript (Base UI vs Radix UI)

• Causa: Usar un bloque Radix UI en un proyecto que solo tiene Base UI instalado, o viceversa.
• Síntomas: Module not found: Can't resolve '@radix-ui/react-...' o Cannot find module '@base-ui/react'.
• Solución:
  • Si tu proyecto usa Base UI: instala la variante Base UI estándar (@shadcn-space/<nombre>). Asegúrate de que @base-ui/react esté instalado (pnpm add @base-ui/react).
  • Si tu proyecto usa Radix UI: instala la variante Radix (@shadcn-space/radix/<nombre>). Asegúrate de que los paquetes @radix-ui/react-* requeridos estén presentes.
  • Para migrar un proyecto existente de Radix a Base UI, sigue la Guía de Migración.

4. Problema: Mensaje "El archivo ya existe" o conflicto

• Causa: El componente o un archivo de dependencia subyacente ya estaba instalado.
• Solución: Pasa la bandera --overwrite:

  npx shadcn@latest add @shadcn-space/hero-01 --overwrite
  

5. Problema: Estilos Rotos o Colores Faltantes

• Causa: Faltan tokens de color semánticos (--background, --foreground, --primary, --border, etc.) en globals.css.
• Solución: ShadcnSpace utiliza tokens estándar de variables CSS. Asegúrate de que tu globals.css o @theme de Tailwind CSS v4 incluya tokens de diseño semánticos. No uses códigos hexadecimales arbitrarios.

6. Problema: components.json No Encontrado

• Causa: El proyecto aún no se ha inicializado con el CLI de shadcn.
• Solución: Ejecuta npx shadcn@latest init primero en la raíz de tu proyecto.

---

Directorio de Documentación y Ayuda

Cuando necesites documentación detallada, guías o asistencia, visita estas páginas de documentación oficiales:

Guía / Recurso	URL	Qué Encontrarás
Introducción de Inicio	https://shadcnspace.com/docs/getting-started/introduction	Descripción general, filosofía e introducción al repositorio
Guía de Instalación del CLI	https://shadcnspace.com/docs/getting-started/how-to-use-shadcn-cli	Tutorial completo del CLI, v3 vs v2, guía en video y solución de problemas
Migración de Radix UI a Base UI	https://shadcnspace.com/docs/getting-started/migrate-to-baseui	Guía paso a paso para migrar código de asChild a render y Positioner
Guía de Configuración del Servidor MCP	https://shadcnspace.com/docs/getting-started/mcp-server-docs	Configuración de Cursor, Windsurf, Claude Code y otros IDEs de IA
Guía de Uso de Componentes	https://shadcnspace.com/docs/getting-started/component	Primitivas UI, botones, menús desplegables, diálogos, campos de entrada
Guía de Bloques	https://shadcnspace.com/docs/getting-started/blocks	Marketing, héroes, precios, testimonios, cuadrículas bento y paneles de control
Guía de Prompts para IA	https://shadcnspace.com/docs/getting-started/copy-prompt	Prompts para páginas de aterrizaje de un solo paso y composición de paneles
Constructor Interactivo del CLI	https://shadcnspace.com/cli	Constructor visual de comandos personalizados para estilos, temas e íconos
Guía de Abrir en v0	https://shadcnspace.com/docs/getting-started/open-v0	Abrir y personalizar bloques de ShadcnSpace dentro de v0
Galería Interactiva de Bloques	https://shadcnspace.com/blocks	Vista previa visual en vivo y código de copia para más de 100 bloques
Catálogo de Componentes	https://shadcnspace.com/components	Micro-interacciones, texto animado, dock, marquee
Plantillas de Página Completa	https://shadcnspace.com/templates	Plantillas de página completas listas para producción
Issues de GitHub y Comunidad	https://github.com/shadcnspace/shadcnspace/issues	Reportes de errores, solicitudes de funciones y discusiones de la comunidad

---

Integración del Servidor MCP de ShadcnSpace

Conecta el servidor MCP oficial de ShadcnSpace a tu IDE de IA (Cursor, Windsurf, Claude Code, Lovable, Bolt o v0) para inspeccionar, buscar e instalar bloques de UI directamente desde tu sesión de chat.

Configuración en Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "shadcnspace": {
      "url": "https://mcp.shadcnspace.com/mcp",
      "headers": {
        "Authorization": "Bearer [email protected]:tu-clave-de-licencia"
      }
    }
  }
}

(Los usuarios del nivel gratuito pueden omitir el campo headers; los bloques gratuitos se instalan sin autenticación).

Configuración en Windsurf

En Configuración de Windsurf → Servidores MCP, añade:

• URL del Servidor: https://mcp.shadcnspace.com/mcp
• Autorización: Bearer [email protected]:tu-clave-de-licencia

Configuración en Claude Code

claude mcp add shadcnspace https://mcp.shadcnspace.com/mcp

Configuración en Lovable y Bolt

• URL del Servidor: https://mcp.shadcnspace.com/mcp
• Transporte: HTTP
• Autenticación: Token Bearer [email protected]:tu-clave-de-licencia

Herramientas MCP Disponibles

Herramienta	Propósito
searchBlocks	Buscar bloques por palabras clave (ej. hero, pricing, stats, sidebar)
listBlocks	Listar todos los bloques disponibles en ShadcnSpace
getBlockInstall	Devuelve el comando CLI exacto para instalar un bloque (Base UI o Radix UI)
searchPages	Buscar plantillas de página completa
getPageInstall	Devuelve el comando de instalación para una página completa
listInstalledBlocks	Inspeccionar bloques ya instalados en el proyecto actual
get_audit_checklist	Devuelve una lista de verificación de accesibilidad, tematización y diseño responsive

---

Patrones de Uso y Prompts para Agentes

Al dar instrucciones a un agente de IA en Cursor, Claude Code o Windsurf, utiliza estos patrones estructurados:

Generación de un Bloque Individual

Agrega una sección de héroe de alta conversión para mi SaaS usando ShadcnSpace Hero 01 (Base UI).

Crea una sección de precios con alternancia mensual y anual usando ShadcnSpace Radix UI Pricing 01.

Agrega una barra lateral de administración y tarjetas de estadísticas usando bloques de panel de ShadcnSpace.

Composición de una Página de Aterrizaje Completa (En un Solo Paso)

Construye una página de aterrizaje SaaS completa usando bloques de ShadcnSpace:
- Barra de navegación: Barra de navegación vítrea y pegajosa de ShadcnSpace
- Héroe: Hero 01 con insignia interactiva y vista previa de video
- Características: Bento Grid 01 con micro-animaciones
- Prueba Social: Testimonial Marquee de ShadcnSpace
- Precios: Pricing 01 con 3 niveles y alternancia de facturación

...

[truncado para traducción]