ui-rules

Reglas de Diseño Frontend — Anti-UI Genérica de IA

Documento operativo: define qué puede y qué no puede hacer la IA al generar interfaces, qué tokens debe usar y cómo verificar el resultado. Stack objetivo: React/Vite + Tailwind 4 + tokens CSS. Aplica a UI de producto (dashboards, formularios, tablas) y a páginas de marketing.

---

0. Cómo trabajar con IA en este sistema

Esta sección es contractual: define el rol de la IA y el flujo de trabajo. Si algo de aquí se rompe, el resto de las reglas dejan de aplicar bien.

0.1 Rol de la IA

• La IA es implementador, no director creativo. No decide el estilo visual global; consume tokens, componentes y layouts ya definidos.
• Prompts prohibidos: "haz que se vea bonito", "modern UI", "diseño minimal SaaS", "como Tailwind UI / Vercel / Linear".
• Cada prompt debe especificar: (a) qué sección se está construyendo, (b) qué componentes existentes puede usar, (c) qué tokens están disponibles, (d) cuál es el objetivo de la sección.
• Si la IA necesita un componente o patrón que no existe, lo describe primero en texto para aprobación. No inventa.

0.2 Flujo de trabajo

• Trabajar sección por sección, no la página completa en un solo prompt.
• Antes de pedir UI nueva, definir 3-5 referencias concretas (capturas) explicando qué tomar de cada una: layout, spacing, jerarquía, tono.
• La IA produce el primer draft estructural. El ajuste fino (spacing, copy, jerarquía) se hace manualmente o en iteraciones cortas.
• Al finalizar, la IA corre el checklist de auto-auditoría (sección 8) sobre su propio output.

0.3 Sistema de componentes permitidos

• La IA solo usa componentes presentes en la biblioteca: Button, Card, Section, Stack, Grid, Badge, Input, Table, StatCard, EmptyState, Skeleton (lista a mantener en components/README.md).
• Cada componente tiene props documentadas y variantes cerradas. La IA no agrega variantes nuevas sin aprobación.
• Los componentes no aceptan valores arbitrarios de spacing/color/radius: solo tokens.

---

1. Reglas críticas

Estas son las que rompen la sensación de "template AI" en primera mirada. Si una sola falla, el resultado se siente genérico aunque todo lo demás esté bien.

Regla 1.1 — Sin gradientes decorativos

Prohibido:

• linear-gradient o radial-gradient en botones, inputs, cards, headers o fondos de sección.
• Esquemas de color "trending" azul-violeta/morado/índigo y gradientes neon-SaaS.
• Blobs, orbs de luz, mesh gradients o fondos abstractos difusos.
• background-clip: text con gradientes en headings.
• Sombras dramáticas (box-shadow con blur > 40px o spread positivo grande).

Patrón válido:

• Botones: background: var(--color-primary) sólido. Hover: misma base con oklch ajustando luminosidad ±0.04.
• Fondos de sección: var(--color-bg) o var(--color-surface) planos, según data-theme.
• Si necesitas variación visual: cambia la superficie (--color-surface → --color-surface-elevated), no añadas gradiente.

Excepciones permitidas:

• Escalas de data viz (heatmaps, choropleths, sparklines con relleno) usando una rampa definida en tokens.
• Skeleton shimmer (gradiente animado en placeholders de carga).
• Fade overlays funcionales (ej: indicar scroll horizontal con fade en bordes de tabla).

Regla 1.2 — Layout asimétrico en grupos de features

Prohibido:

• 3 columnas idénticas tipo "ícono en círculo + título + descripción".
• Íconos dentro de círculos o cuadrados con fondo de color de acento.
• Diferenciar cards con paletas distintas (card azul, card verde, card naranja).

Patrón válido:

• Layout bento 2+1: una card grande con visual real del producto + dos cards pequeñas de texto.
• Stack lateral: lista vertical de features con la principal expandida y las secundarias colapsadas.
• Narrativa en zig-zag: secciones alternadas imagen-texto / texto-imagen.
• La jerarquía se establece por tamaño, densidad de contenido y posición, nunca por color.

Ejemplo de prompt correcto:

"Construye una sección de features con layout bento 2+1: la card grande (col-span-2) muestra captura del módulo de visitas con un título corto encima; las dos cards pequeñas son pares título+párrafo sobre reporting y permisos. Usa Card variante surface-elevated para la grande, surface para las pequeñas."

Regla 1.3 — Alineación izquierda por defecto

Prohibido:

• Centrar body copy, descripciones de features, contenido de cards, items de lista, contenido de tablas.
• text-align: center en bloques de más de una línea.

Patrón válido:

• Hero headline corto (≤ 8 palabras) y tagline: pueden ir centrados si la composición lo pide, pero el CTA mantiene la misma alineación.
• Formularios, listas, tablas, cards y contenido editorial: alineados a la izquierda con max-width controlado (típico: 65ch para prosa, var(--container-md) para layouts).

Regla 1.4 — Copy específico, no genérico

Prohibido:

• Frases plantilla: "Empowering your journey", "Unlock the power of...", "Your all-in-one solution", "Welcome to [nombre]", "Transform your business", "Streamline your workflow".
• Lorem ipsum o texto de relleno en cualquier draft, ni siquiera temporal.
• Headlines abstractos que no nombran el dominio del producto.

Fórmula de headline válida:

[verbo activo concreto] + [audiencia específica] + [resultado medible o diferenciador]

• ❌ "Optimiza tu negocio con nuestra plataforma todo-en-uno."
• ✅ "Registra visitas técnicas desde el celular sin conexión y sincroniza al volver a cobertura."

Regla práctica: si el headline funciona tal cual para otro producto de otra industria, está mal escrito.

---

2. Sistemas de diseño (tokens)

Todo lo visual sale de tokens. Cero valores arbitrarios. Los tokens viven en theme.css (o @theme si es Tailwind 4) y se consumen vía variables CSS o utilidades del framework.

2.1 Color

:root[data-theme="light"] {
  --color-bg: oklch(0.99 0 0);
  --color-surface: oklch(0.97 0 0);
  --color-surface-elevated: oklch(1 0 0);
  --color-text: oklch(0.2 0 0);
  --color-text-muted: oklch(0.45 0 0);
  --color-border: oklch(0.2 0 0 / 0.12);

  --color-primary: oklch(0.55 0.18 250);
  --color-primary-hover: oklch(0.51 0.18 250);
  --color-primary-active: oklch(0.47 0.18 250);
  --color-primary-soft: oklch(0.95 0.04 250);

  --color-success: oklch(0.65 0.15 145);
  --color-warning: oklch(0.75 0.15 75);
  --color-danger: oklch(0.6 0.2 25);
}

Reglas:

• Un solo color de acento principal. Variantes (hover, active, soft) se derivan ajustando l en oklch.
• Máximo 2 colores no-neutrales visibles en cualquier viewport.
• Colores adicionales solo en data visualization o estados semánticos (success/warning/danger).

Dark mode:

• Las superficies en dark suben en luminosidad cuando se elevan (bg < surface < surface-elevated), no bajan.
• Las sombras se reemplazan por bordes sutiles (oklch(1 0 0 / 0.08)).
• Los acentos pierden saturación (chroma baja ~15%) para no quemar en OLED.
• Tokens separados por modo, mismo nombre.

2.2 Tipografía

--font-sans: "Satoshi", system-ui, sans-serif;
--font-display: "Boska", "Satoshi", serif;

--text-xs: 0.75rem;    /* 12px — meta, labels */
--text-sm: 0.875rem;   /* 14px — botones, nav */
--text-base: 1rem;     /* 16px — body */
--text-lg: 1.125rem;   /* 18px — lead paragraphs */
--text-xl: 1.5rem;     /* 24px — h3 */
--text-2xl: 2rem;      /* 32px — h2 */
--text-3xl: clamp(2.5rem, 5vw, 3.5rem);  /* h1 / hero */

Reglas:

• body mínimo 16px. Labels/meta mínimo 12px. Nunca bajar de ahí.
• --font-display solo desde --text-xl (24px) hacia arriba.
• Máximo 2 familias tipográficas. Máximo 5 combinaciones distintas de size + weight + line-height por página.
• Fuentes prohibidas como principal: Inter, Roboto, Open Sans, Montserrat, Poppins, Nunito.
• Preferidas (Fontshare u otros): Satoshi, General Sans, Cabinet Grotesk, Boska, Zodiak, Switzer.

2.3 Spacing

--space-1: 0.25rem;    /* 4px */
--space-2: 0.5rem;     /* 8px */
--space-3: 0.75rem;    /* 12px */
--space-4: 1rem;       /* 16px */
--space-6: 1.5rem;     /* 24px */
--space-8: 2rem;       /* 32px */
--space-12: 3rem;      /* 48px */
--space-16: 4rem;      /* 64px */
--space-20: 5rem;      /* 80px */
--space-24: 6rem;      /* 96px */

Reglas:

• Todo spacing referencia tokens. Cero valores arbitrarios en px sin token (13px, 22px están prohibidos).
• Gaps entre elementos: dentro de una card --space-3, entre cards --space-6, entre secciones --space-16 a --space-24.

2.4 Border-radius

--radius-sm: 0.25rem;   /* 4px — badges, chips */
--radius-md: 0.5rem;    /* 8px — inputs, buttons */
--radius-lg: 0.75rem;   /* 12px — cards pequeñas */
--radius-xl: 1rem;      /* 16px — cards grandes, modales */
--radius-2xl: 1.5rem;   /* 24px — paneles, hero containers */
--radius-full: 9999px;  /* pills, avatares circulares */

Reglas:

• Elementos pequeños = radio pequeño, elementos grandes = radio mayor. Nunca el mismo radio en botón y en card contenedora.
• Radio anidado: inner-radius = outer-radius - padding. Evita el efecto "burbuja dentro de burbuja".
• Nunca hardcodear border-radius: 9999px indiscriminadamente.

2.5 Sombras y elevación

--shadow-1: 0 1px 2px oklch(0.2 0 0 / 0.06);
--shadow-2: 0 4px 12px oklch(0.2 0 0 / 0.08);
--shadow-3: 0 12px 32px oklch(0.2 0 0 / 0.12);

• Light mode: 3 niveles máximo, sutiles.
• Dark mode: reemplazar sombras por bordes (border: 1px solid oklch(1 0 0 / 0.08)).
• Hover en cards interactivas: subir un nivel de sombra (--shadow-1 → --shadow-2), no transform: scale(1.05).

2.6 Ritmo de secciones (marketing)

.section-dense    { padding-block: var(--space-12); }
.section-default  { padding-block: var(--space-20); }
.section-spacious { padding-block: var(--space-24); }

• Alternar tipos a lo largo de la página. Prohibido usar dos section-default consecutivas.
• Variar también la estructura del grid sección por sección (2 col, 3 col, sidebar, full-bleed).

---

3. UI de producto (dashboards, tablas, formularios)

3.1 Tablas

• Sin zebra striping por default. Activar con --color-surface muy sutil en filas pares si la tabla supera ~12 filas.
• Hover por fila: cambio a --color-surface-elevated, cursor: pointer solo si la fila es clicable.
• Headers sticky cuando la tabla scrollea (position: sticky; top: 0).
• Densidad como variante: compact (--space-2 vertical), comfortable (--space-3, default), spacious (--space-4).
• Alineación: texto a la izquierda, números a la derecha, fechas a la izquierda con formato consistente. Encabezados siguen la alineación de su columna.
• Acciones de fila: agrupadas a la derecha en una sola columna con íconos del mismo set.

Prohibido: bordes gruesos entre filas; color de fondo distinto por estado de fila (usar badge en columna de estado); centrar contenido textual.

3.2 Filtros y toolbars

• Una sola toolbar arriba de la tabla, alineada a la izquierda. Search a la izquierda, filtros activos como chips removibles después, acciones (export, crear) a la derecha.
• Chips de filtro activo: var(--color-primary-soft) de fondo, label legible, X para cerrar. Máximo 4-5 visibles, el resto colapsa en "+ N filtros".
• Filtros complejos (rangos, multi-select): en panel lateral o popover, no acumulados en la toolbar.

3.3 StatCards / KPIs

Estructura obligatoria (en este orden):

1. Label pequeño en --text-xs, muted
2. Valor grande en --text-2xl o más, --font-display si > 24px
3. Delta opcional: ↑ 12% vs mes anterior, con color semántico

Prohibido: valor pequeño y label grande (jerarquía invertida); íconos decorativos grandes al lado del valor; cards con fondo de color por categoría; más de 4 KPIs en una fila.

3.4 Formularios

• Labels arriba del input, alineados a la izquierda, en --text-sm. No labels flotantes.
• Helper text bajo el input en --text-xs muted. Error text en el mismo lugar con --color-danger.
• Inputs altura mínima 40px (44px touch target en mobile).
• Agrupar campos relacionados con --space-6 entre grupos, --space-3 entre campos del mismo grupo.
• Botón primario abajo a la derecha en desktop, full-width en mobile.
• Validación: al hacer blur del campo, no en cada keystroke.

3.5 Estados defensivos

Loading:

• Skeleton shimmer con estructura del contenido real.
• Cargas por sección, no overlay global de página.
• Spinner centrado solo para acciones de < 2s en botones.

Empty state:

• Estructura: ilustración o ícono neutro pequeño + mensaje específico + acción primaria.
• "Aún no has registrado visitas este mes" > "No hay datos".
• Empty state de tabla: dentro del <tbody>, ocupando una fila con colspan completo.

Error:

• Mensaje específico: qué falló y qué puede hacer el usuario. Nunca códigos crudos ni stack traces.
• Ejemplo: "No pudimos conectar con el servidor de visitas. Revisa tu conexión y reintenta." + botón "Reintentar".
• Errores de campo: inline bajo el input. Errores de operación: toast o banner contextual.

---

4. Páginas de marketing

4.1 Estructura

• Prohibido el layout plantilla AI: hero → 3 features idénticas → 3 cards → testimonio → pricing → CTA.
• Cada página tiene un objetivo principal (signup, demo, descarga). El layout se diseña alrededor de ese objetivo.
• Navegación principal: máximo 5-7 items agrupados por caso de uso, no por módulos técnicos.

4.2 Hero

• Headline siguiendo la fórmula de Regla 1.4.
• Subhead opcional, máximo 2 líneas.
• Un CTA primario claro + uno secundario discreto (link, no botón secundario fuerte).
• Visual: captura real del producto, no ilustración stock.

4.3 Pricing

• Tabla, no 3 cards centradas. Las cards centradas con "Most popular" en el medio son el patrón template más obvio.
• Diferenciar tiers por contenido (qué incluye), no por color de fondo.
• Precio grande, label de periodo pequeño al lado, no debajo.

---

5. Imágenes, ilustraciones e iconos

• Prohibido: ilustraciones stock tipo undraw, 3D blobs corporativos, isométricos genéricos.
• Preferido: capturas reales del producto, diagramas propios, shapes geométricas neutras (líneas, grids, formas SVG simples).
• Íconos: un solo set por proyecto. Outline o filled, no mezclados. Mismo grosor de línea (1.5px o 2px). Tamaño consistente: 16px en meta, 20px en botones, 24px en headers.
• Todas las imágenes con aspect-ratio definido en CSS para evitar CLS.
• loading="lazy" en imágenes below-the-fold. Hero y above-the-fold sin lazy.

---

6. Micro-interacciones y accesibilidad

6.1 Animaciones

• Duración corta: 150-200ms. Más largo se siente lento.
• Easing: cubic-bezier(0.2, 0, 0, 1) para entradas, cubic-bezier(0.4, 0, 1, 1) para salidas. Nunca linear ni ease.
• Solo cuando aportan claridad: expandir panel, feedback de botón, transición de estado.
• Obligatorio respetar prefers-reduced-motion.

6.2 Estados interactivos

Todos los elementos clicables tienen 4 estados visualmente distintos:

1. default
2. hover (cambio sutil de color o sombra)
3. active (presionado, color más oscuro)
4. focus-visible (anillo de 2px con --color-primary y outline-offset: 2px)

Prohibido: quitar el outline sin reemplazo. outline: none solo si hay :focus-visible con anillo equivalente.

6.3 Accesibilidad

• Touch targets: mínimo 44×44px en mobile.
• Contraste WCAG AA: 4.5:1 en body, 3:1 en texto grande (≥ 18px).
• alt en todas las imágenes; vacío (alt="") si es decorativa.
• aria-label en botones de solo ícono.
• Navegación completa por teclado: Tab order lógico, Escape cierra modales/popovers, flechas en menús y listas seleccionables.
• Anuncios de cambios dinámicos con aria-live para toasts y errores.

---

7. Performance

• Fuentes con font-display: swap + preload de la principal.
• Imágenes con width y height declarados o aspect-ratio CSS para evitar CLS.
• Code split por ruta. Componentes pesados (charts, editores) con React.lazy.
• Skeleton shimmer durante carga inicial de datos.
• Tablas grandes (>100 filas): virtualización (@tanstack/react-virtual o similar).

---

8. Checklist de auto-auditoría

Al terminar cualquier UI generada, la IA corre este checklist y reporta resultado. Cualquier "sí" en una pregunta de prohibición es falla.

8.1 Críticas (cualquier falla = rehacer)

• ¿Hay algún linear-gradient o radial-gradient fuera de data viz o skeleton?
• ¿Hay íconos dentro de círculos/cuadrados con color de acento?
• ¿Hay 3 columnas idénticas de features con la misma estructura?
• ¿Hay body copy centrado fuera del hero?
• ¿El headline funciona tal cual para otro producto de otra industria?
• ¿Hay border-left de color de acento como decoración de card?
• ¿Hay texto Lorem ipsum o placeholder genérico?

8.2 Sistémicas (revisar y corregir)

• ¿Todos los valores de spacing, color, radius vienen de tokens?
• ¿Hay valores en px sin token (13px, 22px)?
• ¿Se usan más de 2 familias tipográficas o más de 5 estilos distintos?
• ¿Cards e inputs comparten el mismo border-radius?
• ¿Las superficies en dark mode bajan en luminosidad al elevarse (debe ser al revés)?
• ¿Hay dos secciones consecutivas con el mismo padding-block?

8.3 Producto (si aplica)

• ¿Las columnas numéricas de la tabla están alineadas a la derecha?
• ¿Los StatCards tienen label arriba, valor grande abajo?
• ¿Los empty states tienen mensaje específico al contexto y acción primaria?
• ¿Los errores muestran qué hacer, no códigos crudos?

8.4 Pulido

• ¿Todos los elementos interactivos tienen 4 estados (default/hover/active/focus-visible)?
• ¿Las animaciones respetan prefers-reduced-motion?
• ¿Las imágenes tienen aspect-ratio o dimensiones declaradas?
• ¿Los touch targets en mobile son ≥ 44×44px?