Este template define la estructura recomendada para la guía de diseño de un proyecto construido con AI coding agents. Está extraído de la GUIA_DISENO.md de Virso (1134 líneas co-creadas con Claude Code durante 5 fases de implementación). Principio: Este documento es EVOLUTIVO. No se escribe completo al inicio. Se empieza con las secciones obligatorias y crece conforme se implementa. Cada sesión de implementación puede agregar gotchas, componentes, o patrones nuevos. Relación con otros documentos:

• UX_PATTERNS_PROTOCOL.md = principios agnósticos (Capa 1, no cambia entre proyectos)
• GUIA_DISENO.md = especificaciones de proyecto (Capa 2, este documento, único por proyecto)

​

Cómo usar este template

1. Copiar como docs/GUIA_DISENO.md en tu proyecto
2. Llenar las secciones marcadas como [OBLIGATORIO] antes de la primera sesión de implementación de UI
3. Las secciones [CRECE CON EL PROYECTO] se van llenando conforme se implementa
4. Las secciones [OPCIONAL] se agregan si el proyecto las necesita
5. Eliminar toda la guía de uso y los comentarios <!-- --> cuando el documento esté en uso

​

Índice

1. Paleta de colores — OBLIGATORIO
2. Tipografía — OBLIGATORIO
3. Espaciado y bordes — OBLIGATORIO
4. Sistema de temas — OBLIGATORIO si hay dark mode
5. Layout principal — OBLIGATORIO
6. Componentes UI — CRECE CON EL PROYECTO
7. Patrones de página — CRECE CON EL PROYECTO
8. Animaciones y motion — OPCIONAL
9. Iconografía — OBLIGATORIO
10. Accesibilidad — OBLIGATORIO
11. Internacionalización — OPCIONAL
12. Gotchas del framework CSS — CRECE CON EL PROYECTO
13. Responsive design — OBLIGATORIO
14. Estructura de archivos UI — OBLIGATORIO
15. Efectos visuales especiales — OPCIONAL
16. Checklist para nuevas funcionalidades — OBLIGATORIO

​

Principio fundamental

​

1. Paleta de colores [OBLIGATORIO]

​

1.1 Colores principales

​

1.2 Reglas de contraste

• {Color problemático}: ratio {X:1} contra {fondo}. Solución: {token alternativo}
• Regla: {clase para texto de marca} para texto legible, NUNCA {clase primary} sobre fondos claros

​

1.3 Tokens del tema

/* Copiar los tokens CSS de tu proyecto aquí.
   Esto es la referencia definitiva para la AI. */

/* Light theme */
--color-primary: {valor};
--color-background: {valor};
--color-foreground: {valor};
--color-card: {valor};
--color-card-foreground: {valor};
--color-muted: {valor};
--color-muted-foreground: {valor};
--color-border: {valor};
/* ... */

/* Dark theme (si aplica) */
/* ... */

​

1.4 Tokens semánticos de estado [CRECE CON EL PROYECTO]

​

1.5 Fondos semánticos (transparencias) [CRECE CON EL PROYECTO]

​

2. Tipografía [OBLIGATORIO]

​

2.1 Font stacks

--font-sans: {fuente body}, ui-sans-serif, system-ui, sans-serif;
--font-heading: {fuente headings}, {fallback};
/* --font-mono: {fuente mono}; /* si aplica */

​

2.2 Escala tipográfica

​

2.3 Reglas

• {Fuente} en todos los headings y títulos
• Nunca {peso prohibido} (ej: font-thin, font-light)
• {Otras reglas tipográficas del proyecto}

​

3. Espaciado y bordes [OBLIGATORIO]

​

3.1 Border radius

​

3.2 Sombras

--shadow-card: {valor light};  /* light */
--shadow-card: {valor dark};   /* dark (si aplica) */

​

3.3 Espaciado común

​

4. Sistema de temas [OBLIGATORIO si hay dark mode]

​

4.1 Arquitectura

{Librería de temas} con {estrategia (class/attribute)}, defaultTheme="{default}"

​

4.2 Reglas de adaptación entre modos

​

4.3 Qué NO hacer

• NO dejar el mismo color idéntico en ambos modos
• NO invertir el color simplemente
• {Otras reglas específicas del proyecto}

​

5. Layout principal [OBLIGATORIO]

​

5.1 Estructura

{Diagrama ASCII del layout principal}

Ejemplo:
SidebarProvider
├── Sidebar (collapsible)
└── ContentArea
    ├── TopBar (sticky, header)
    └── main (contenido scrolleable)

​

5.2 Sidebar

• Modo: {collapsible, fixed, drawer, etc.}
• Ancho expandido: {valor}
• Ancho colapsado: {valor}
• Mobile: {Sheet, drawer, overlay, etc.}
• Persistencia: {cookie, localStorage, etc.}
• Keyboard shortcut: {atajo}

​

5.3 TopBar / Header

{Diagrama ASCII del header}

​

5.4 Focus layout (segundo nivel) [si aplica]

​

Header del focus layout

{variante 1} → {descripción}
{variante 2} → {descripción}

​

6. Componentes UI [CRECE CON EL PROYECTO]

​

6.1 Biblioteca base

​

6.2 Componentes con reglas especiales

​

{Nombre del componente}

• Variantes: {listar}
• Regla especial: {lo que la AI debe saber}
• Gotcha: {error común al usarlo}

​

7. Patrones de página [CRECE CON EL PROYECTO]

​

7.1 {Nombre del patrón} (ej: Auth Pages)

​

7.2 {Nombre del patrón} (ej: Listado con filtros)

​

7.3 Empty state

​

8. Animaciones y motion [OPCIONAL]

​

8.1 Keyframes

​

8.2 Reglas

• Solo animar transform y opacity para 60fps
• Duraciones: {micro}ms (micro), {standard}ms (transiciones), {entrance}ms (entradas)
• NO animar height, width, top, left
• will-change: transform solo donde sea estrictamente necesario

​

8.3 Reduced motion

@media (prefers-reduced-motion: reduce) {
  /* Desactivar todas las animaciones */
}

​

9. Iconografía [OBLIGATORIO]

• Iconos decorativos: aria-hidden="true"
• NO mezclar librerías de iconos

​

10. Accesibilidad [OBLIGATORIO]

​

10.1 Contraste WCAG AA

• Texto normal: 4.5:1 mínimo
• Texto grande: 3:1 mínimo
• {Notas específicas del proyecto sobre contraste}

​

10.2 Focus visible

​

10.3 ARIA patterns

​

10.4 Formularios accesibles

<!-- Ejemplo de implementación con aria-describedby + aria-invalid -->
{código de ejemplo de tu stack}

​

10.5 Landmarks

​

10.6 Heading hierarchy

<h1> — {uso}
<h2> — {uso}
<h3> — {uso}

​

11. Internacionalización [OPCIONAL]

• Librería: {nombre y versión}
• Idiomas: {idiomas soportados}
• Mensajes: {ruta a archivos de mensajes}

• NUNCA hardcodear strings de UI
• {Reglas de formato, variables, pluralización}

​

12. Gotchas del framework CSS [CRECE CON EL PROYECTO]

​

12.1 {Gotcha 1}

/* MAL */  {código incorrecto}
/* BIEN */ {código correcto}

​

12.2 {Gotcha 2}

​

13. Responsive design [OBLIGATORIO]

​

13.1 Breakpoints

​

13.2 Patrones responsive por componente

​

14. Estructura de archivos UI [OBLIGATORIO]

{Árbol de archivos de UI del proyecto}

Ejemplo:
packages/ui/src/
├── components/
│   ├── ui/              ← componentes base
│   └── {custom}.tsx     ← componentes custom
├── lib/utils.ts         ← utilidades (cn, etc.)
└── index.ts             ← barrel exports

​

15. Efectos visuales especiales [OPCIONAL]

​

15.1 {Nombre del efecto}

• Cómo funciona: {descripción técnica breve}
• Dónde se usa: {componentes que lo usan}
• Reglas:
  • {Regla 1 — qué respetar para que el efecto funcione}
  • {Regla 2 — qué NO hacer}

​

16. Checklist para nuevas funcionalidades [OBLIGATORIO]

​

Colores y tokens

• Cero colores hardcodeados — solo tokens semánticos
• {Regla de contraste específica del proyecto}

​

Componentes

• Reutilizar componentes existentes de {librería}
• {Librería de iconos} para todos los iconos
• {Patrón de border-radius} respetado

​

Tema (si aplica dark mode)

• Funcional en light y dark sin glitches
• Contraste WCAG AA verificado

​

Accesibilidad

• Focus visible en todos los interactivos
• aria-label en botones de solo ícono
• aria-hidden="true" en iconos decorativos
• role="alert" en errores dinámicos
• Heading hierarchy correcta
• {Otras reglas de a11y del proyecto}

​

i18n (si aplica)

• Textos via sistema de i18n — no hardcodeados

​

Responsive

• Funciona en mobile ({ancho mínimo}) y desktop

​

Framework CSS

• {Gotcha 1 verificado}
• {Gotcha 2 verificado}

​

Notas sobre este template

​

Secciones obligatorias (llenar antes de implementar UI)

1. Paleta de colores (tokens mínimos)
2. Tipografía (font stacks + escala)
3. Espaciado y bordes (radios + espaciado común)
4. Layout principal (estructura + sidebar)
5. Iconografía (librería + tamaños)
6. Accesibilidad (contraste + ARIA + landmarks)
7. Responsive (breakpoints)
8. Estructura de archivos UI
9. Checklist

​

Secciones que crecen con el proyecto

• Componentes UI → agregar cada componente nuevo con sus reglas
• Patrones de página → agregar cada tipo de página implementado
• Gotchas → agregar cada bug/gotcha descubierto
• Tokens de estado → agregar conforme se definen estados del dominio
• Fondos semánticos → agregar conforme se establecen patrones de color

​

Secciones opcionales (agregar si el proyecto las necesita)

• Sistema de temas (solo si hay dark mode)
• Animaciones (solo si hay un sistema definido)
• i18n (solo si hay multi-idioma)
• Efectos visuales especiales (glassmorphism, gradientes, etc.)

​

Señales de que tu guía necesita actualización

• La AI genera un componente con estilos que no siguen la guía → agregar la regla
• Descubres un bug de CSS que la AI repite → agregar a gotchas
• Implementas un patrón de página nuevo → documentar en sección 7
• Cambias tokens de color → actualizar sección 1
• Agregas un componente a la librería → documentar en sección 6 si tiene reglas especiales

​

Tamaño esperado

• Al inicio: ~100-150 líneas (secciones obligatorias con valores mínimos)
• Proyecto maduro: ~500-1000+ líneas (como la guía de Virso con 1134 líneas)
• Esto es normal y esperado — la guía DEBE crecer con el proyecto