Documentation Index

Fetch the complete documentation index at: https://ai-first.falcux.com/llms.txt

Use this file to discover all available pages before exploring further.

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