ElKrapulito/calucha-landing

Habilidad de Estilizado de UI

Habilidad integral para crear interfaces de usuario hermosas y accesibles combinando componentes shadcn/ui, estilos utilitarios de Tailwind CSS y sistemas de diseño visual basados en canvas.

Referencia

• shadcn/ui: https://ui.shadcn.com/llms.txt
• Tailwind CSS: https://tailwindcss.com/docs

Cuándo Usar Esta Habilidad

Úsala cuando:

• Construyas UI con frameworks basados en React (Next.js, Vite, Remix, Astro)
• Implementes componentes accesibles (diálogos, formularios, tablas, navegación)
• Estilices con enfoque CSS utilitario
• Creases diseños responsivos y mobile-first
• Implementes modo oscuro y personalización de temas
• Construyas sistemas de diseño con tokens consistentes
• Generes diseños visuales, carteles o materiales de marca
• Prototipes rápidamente con retroalimentación visual inmediata
• Agregues patrones complejos de UI (tablas de datos, gráficos, paletas de comandos)

Stack Principal

Capa de Componentes: shadcn/ui

• Componentes accesibles preconstruidos mediante primitivas de Radix UI
• Modelo de distribución copia-pega (los componentes viven en tu código)
• TypeScript-first con seguridad de tipos completa
• Primitivas componibles para UI complejas
• Instalación y gestión mediante CLI

Capa de Estilizado: Tailwind CSS

• Framework CSS utilitario
• Procesamiento en tiempo de compilación sin sobrecarga en tiempo de ejecución
• Diseño responsivo mobile-first
• Tokens de diseño consistentes (colores, espaciado, tipografía)
• Eliminación automática de código muerto

Capa de Diseño Visual: Canvas

• Composiciones visuales de calidad museística
• Enfoque de diseño basado en filosofía
• Comunicación visual sofisticada
• Mínimo texto, máximo impacto visual
• Patrones sistemáticos y estética refinada

Inicio Rápido

Configuración de Componentes + Estilizado

Instalar shadcn/ui con Tailwind:

npx shadcn@latest init

El CLI pregunta por el framework, TypeScript, rutas y preferencias de tema. Esto configura tanto shadcn/ui como Tailwind CSS.

Agregar componentes:

npx shadcn@latest add button card dialog form

Usar componentes con estilizado utilitario:

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export function Dashboard() {
  return (
    <div className="container mx-auto p-6 grid gap-6 md:grid-cols-2 lg:grid-cols-3">
      <Card className="hover:shadow-lg transition-shadow">
        <CardHeader>
          <CardTitle className="text-2xl font-bold">Analíticas</CardTitle>
        </CardHeader>
        <CardContent className="space-y-4">
          <p className="text-muted-foreground">Ver tus métricas</p>
          <Button variant="default" className="w-full">
            Ver Detalles
          </Button>
        </CardContent>
      </Card>
    </div>
  )
}

Alternativa: Configuración Solo Tailwind

Proyectos Vite:

npm install -D tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite'
export default { plugins: [tailwindcss()] }

/* src/index.css */
@import "tailwindcss";

Guía de Biblioteca de Componentes

Catálogo completo de componentes con patrones de uso, instalación y ejemplos de composición.

Ver: references/shadcn-components.md

Cubre:

• Componentes de formulario e entrada (Button, Input, Select, Checkbox, Date Picker, validación de Form)
• Diseño y navegación (Card, Tabs, Accordion, Navigation Menu)
• Superposiciones y diálogos (Dialog, Drawer, Popover, Toast, Command)
• Retroalimentación y estado (Alert, Progress, Skeleton)
• Componentes de visualización (Table, Data Table, Avatar, Badge)

Tema y Personalización

Configuración de tema, variables CSS, implementación de modo oscuro y personalización de componentes.

Ver: references/shadcn-theming.md

Cubre:

• Configuración de modo oscuro con next-themes
• Sistema de variables CSS
• Personalización de colores y paletas
• Personalización de variantes de componentes
• Implementación de alternancia de tema

Patrones de Accesibilidad

Patrones ARIA, navegación por teclado, soporte para lectores de pantalla y uso accesible de componentes.

Ver: references/shadcn-accessibility.md

Cubre:

• Funcionalidades de accesibilidad de Radix UI
• Patrones de navegación por teclado
• Gestión de enfoque
• Anuncios para lectores de pantalla
• Accesibilidad en validación de formularios

Utilidades de Tailwind

Clases utilitarias principales para diseño, espaciado, tipografía, colores, bordes y sombras.

Ver: references/tailwind-utilities.md

Cubre:

• Utilidades de diseño (Flexbox, Grid, posicionamiento)
• Sistema de espaciado (padding, margin, gap)
• Tipografía (tamaños de fuente, pesos, alineación, altura de línea)
• Colores y fondos
• Bordes y sombras
• Valores arbitrarios para estilizado personalizado

Diseño Responsivo

Puntos de ruptura mobile-first, utilidades responsivas y diseños adaptativos.

Ver: references/tailwind-responsive.md

Cubre:

• Enfoque mobile-first
• Sistema de puntos de ruptura (sm, md, lg, xl, 2xl)
• Patrones de utilidades responsivas
• Consultas de contenedor
• Consultas de ancho máximo
• Puntos de ruptura personalizados

Personalización de Tailwind

Estructura del archivo de configuración, utilidades personalizadas, plugins y extensiones de tema.

Ver: references/tailwind-customization.md

Cubre:

• Directiva @theme para tokens personalizados
• Colores y fuentes personalizados
• Extensiones de espaciado y puntos de ruptura
• Creación de utilidades personalizadas
• Variantes personalizadas
• Organización de capas (@layer base, components, utilities)
• Directiva Apply para extracción de componentes

Sistema de Diseño Visual

Filosofía de diseño basada en canvas, principios de comunicación visual y composiciones sofisticadas.

Ver: references/canvas-design-system.md

Cubre:

• Enfoque de filosofía de diseño
• Comunicación visual sobre texto
• Patrones sistemáticos y composición
• Diseño de color, forma y espacio
• Integración de texto mínimo
• Ejecución de calidad museística
• Sistemas de diseño multipágina

Scripts de Utilidad

Automatización en Python para instalación de componentes y generación de configuración.

shadcn_add.py

Agrega componentes shadcn/ui con manejo de dependencias:

python scripts/shadcn_add.py button card dialog

tailwind_config_gen.py

Genera tailwind.config.js con tema personalizado:

python scripts/tailwind_config_gen.py --colors brand:blue --fonts display:Inter

Mejores Prácticas

1. Composición de Componentes: Construye UI complejas a partir de primitivas simples y componibles
2. Estilizado Utilitario: Usa clases de Tailwind directamente; extrae componentes solo para repetición real
3. Responsive Mobile-First: Comienza con estilos móviles, agrega variantes responsivas
4. Accesibilidad Primero: Aprovecha las primitivas de Radix UI, agrega estados de enfoque, usa HTML semántico
5. Tokens de Diseño: Usa escala de espaciado, paletas de colores y sistema tipográfico consistentes
6. Consistencia de Modo Oscuro: Aplica variantes oscuras a todos los elementos con tema
7. Rendimiento: Aprovecha la purga automática de CSS, evita nombres de clase dinámicos
8. TypeScript: Usa seguridad de tipos completa para mejor experiencia de desarrollo
9. Jerarquía Visual: Deja que la composición guíe la atención, usa espaciado y color intencionalmente
10. Artesanía Experta: Cada detalle importa: trata la UI como un oficio

Navegación de Referencias

Biblioteca de Componentes

• references/shadcn-components.md - Catálogo completo de componentes
• references/shadcn-theming.md - Temas y personalización
• references/shadcn-accessibility.md - Patrones de accesibilidad

Sistema de Estilizado

• references/tailwind-utilities.md - Clases utilitarias principales
• references/tailwind-responsive.md - Diseño responsivo
• references/tailwind-customization.md - Configuración y extensiones

Diseño Visual

• references/canvas-design-system.md - Filosofía de diseño y flujos de trabajo con canvas

Automatización

• scripts/shadcn_add.py - Instalación de componentes
• scripts/tailwind_config_gen.py - Generación de configuración

Patrones Comunes

Formulario con validación:

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
})

export function LoginForm() {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { email: "", password: "" }
  })

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(console.log)} className="space-y-6">
        <FormField control={form.control} name="email" render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl>
              <Input type="email" {...field} />
            </FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <Button type="submit" className="w-full">Iniciar Sesión</Button>
      </form>
    </Form>
  )
}

Diseño responsivo con modo oscuro:

<div className="min-h-screen bg-white dark:bg-gray-900">
  <div className="container mx-auto px-4 py-8">
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
      <Card className="bg-white dark:bg-gray-800 border-gray-200 dark:border-gray-700">
        <CardContent className="p-6">
          <h3 className="text-xl font-semibold text-gray-900 dark:text-white">
            Contenido
          </h3>
        </CardContent>
      </Card>
    </div>
  </div>
</div>

Recursos

• Documentación de shadcn/ui: https://ui.shadcn.com
• Documentación de Tailwind CSS: https://tailwindcss.com
• Radix UI: https://radix-ui.com
• Tailwind UI: https://tailwindui.com
• Headless UI: https://headlessui.com
• v0 (Generador de UI con IA): https://v0.dev