diseño-de-ui

Habilidad de Diseño de UI

Habilidad completa para crear interfaces de usuario hermosas y accesibles combinando componentes shadcn/ui, estilos utility-first 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)
• Estés diseñando con un enfoque CSS utility-first
• Crees layouts responsivos 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
• Necesites prototipado rápido con retroalimentación visual inmediata
• Añadas patrones de UI complejos (tablas de datos, gráficos, paletas de comandos)

Stack Principal

Capa de Componentes: shadcn/ui

• Componentes accesibles pre-construidos basados en primitivas de Radix UI
• Modelo de distribución copiar-pegar (los componentes viven en tu código)
• TypeScript-first con seguridad de tipos completa
• Primitivas componibles para UIs complejas
• Instalación y gestión basada en CLI

Capa de Estilos: Tailwind CSS

• Framework CSS utility-first
• Procesamiento en tiempo de compilación con cero overhead en runtime
• 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

Rutas de Scripts

Las rutas de scripts en esta habilidad y su carpeta references/ son relativas al directorio que contiene este SKILL.md, no al proyecto: scripts/<archivo> es la carpeta scripts/ propia de esta habilidad, y ../<habilidad>/scripts/<archivo> es una sub-habilidad hermana instalada junto a ella. Construye la ruta completa desde ese directorio (Claude Code lo reporta como el directorio base de la habilidad cuando se carga) y mantén el directorio de trabajo en la raíz del proyecto — los scripts leen y escriben archivos del proyecto como docs/brand-guidelines.md, assets/design-tokens.json o src/ de forma relativa.

Inicio Rápido

Configuración de Componentes + Estilos

Instala shadcn/ui con Tailwind:

npx shadcn@latest init

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

Añade componentes:

npx shadcn@latest add button card dialog form

Usa componentes con estilos utility:

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: 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 input (Button, Input, Select, Checkbox, Date Picker, validación de Formularios)
• Layout 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 foco
• Anuncios para lectores de pantalla
• Accesibilidad en validación de formularios

Utilidades de Tailwind

Clases utility principales para layout, espaciado, tipografía, colores, bordes y sombras.

Ver: references/tailwind-utilities.md

Cubre:

• Utilidades de layout (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 estilos personalizados

Diseño Responsivo

Breakpoints mobile-first, utilidades responsivas y layouts adaptativos.

Ver: references/tailwind-responsive.md

Cubre:

• Enfoque mobile-first
• Sistema de breakpoints (sm, md, lg, xl, 2xl)
• Patrones de utilidades responsivas
• Consultas de contenedor
• Consultas de ancho máximo
• Breakpoints 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 breakpoints
• 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 mínima de texto
• 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

Añade 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

El generador se niega a crear o reemplazar una configuración cuando ya existe algún archivo hermano tailwind.config.js, .cjs, .mjs o .ts. Revisa la configuración reportada primero, luego pasa --force solo cuando la salida en competencia sea intencional:

python scripts/tailwind_config_gen.py --colors brand:blue --force

Mejores Prácticas

1. Composición de Componentes: Construye UIs complejas a partir de primitivas simples y componibles
2. Estilos Utility-First: Usa clases de Tailwind directamente; extrae componentes solo para repetición real
3. Responsivo Mobile-First: Empieza con estilos móviles, superpón variantes responsivas
4. Accesibilidad Primero: Aprovecha las primitivas de Radix UI, añade estados de foco, 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 temáticos
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 espacio 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 Estilos

• references/tailwind-utilities.md - Clases utility 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 en 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>
  )
}

Layout 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