Sistema y Arquitectura

Si el design system tiene composiciones más cuidadas que las páginas reales, el DS es vitrina y el producto es la tienda fea. Los docs deben mostrar componentes exactamente como lucen en producción: mismo padding, mismos colores, mismas constraints. Cuando hay gap entre docs y producto, el equipo deja de confiar en el DS porque "así no se ve en la app". La solución no es bajar la calidad del DS, sino subir la del producto hasta que sean 1:1.

Los z-index numéricos generan guerras de escalación: cada desarrollador suma un número más alto que el anterior hasta llegar a 99999 sin lógica ni jerarquía. Una escala canonica de tokens CSS (--z-dropdown, --z-modal, --z-tooltip, --z-overlay) hace predecible la jerarquía de capas. Combinada con una regla de lint que rechace valores numéricos directos, se elimina la posibilidad de colisiones silenciosas.

Si un archivo acumula más de 3 commits de fixes contradictorios y sigue roto, cada parche nuevo genera regresiones en cascada. Reescribir desde cero, con conocimiento de que patrones fallaron, es más barato que diagnosticar capas de parches superpuestos. La reescritura informada usa los fixes fallidos como spec negativo: sabes exactamente que no funciona, así que el código nuevo evita esas trampas desde el inicio.

Cuando un contenedor flex tiene hijos con position:absolute (tooltips, coachmarks, popovers), el sizing intrinseco de flex entra en conflicto con el posicionamiento absoluto: el tooltip se desplaza, empuja siblings o queda cortado. CSS Grid con áreas nombradas resuelve el problema porque los absolute children no participan en el calculo de columnas, y las grid áreas proporcionan anclas explicitas para posicionar elementos flotantes de forma predecible.

El color rojo en hover debe reservarse exclusivamente para acciones irreversibles. Cuando todo tiene hover rojo, el usuario pierde la capacidad de distinguir entre quitar algo del carrito (trivialmente reversible), descartar un borrador (reversible pero con perdida de trabajo) y eliminar una cuenta (irreversible). Un sistema semántico asigna hover neutro a lo reversible, ambar a lo que implica perdida recuperable y rojo solo a lo verdaderamente destructivo.

Atras/Siguiente son la acción más frecuente en un wizard. En mobile ambos botones deben ocupar el 100% del ancho disponible con flex:1 y min-height:48px, eliminando toda zona muerta. La primaria (Siguiente) lleva fondo accent y font-weight 600; la secundaria (Atras) es ghost/outlined. Acciones terciarias (Descartar, Guardar borrador) pasan a icon-only 32x32 en viewports estrechos. El status pill se oculta progresivamente bajo 540px.

Animaciones ambient (orbs, halos, pulse decorativos) llevan clase .motion-safe para bypass del kill global de prefers-reduced-motion. Sin ese gate, animaciones decorativas corren para todos los usuarios, incluyendo quienes experimentan mareo o malestar con movimiento en pantalla. La clase .motion-safe permite que el sistema detenga solo lo disruptivo (parallax, page transitions, scale grande) mientras conserva la vida visual de elementos ambient que no causan malestar.

Los keyframes de ripple que arrancan a opacity: .7 desde scale 1 producen un "pop" visible en cada ciclo. Ramp correcto: 0% opacity 0 > 8% .55 > 40% .25 > 100% 0. El reset de scale ocurre con opacity 0 (invisible). Duración 6s para ritmo calmado.

Publicar /legal/privacy, /legal/terms, /legal/cookies como superficie global con footer link. Consentimiento biometrico explicito antes de captura de voz/rostro. Banner de disclosure "Soy un asistente con IA" en chatbot. Sin esto, no cumple LFPDPPP (MX), Ley 172-13 (DOM) ni Ley 1581/2012 (CO).

Cada hallazgo sigue: Problema (que falla) > Razón (causa raiz sistemica, no sintoma) > Solución (patrón/principio, no código) > Output esperado (verificación observable: grep, Lighthouse, comportamiento manual reproducible). Severidades: Critica / Alta / Media / Baja.

Instalar agentation (npm) como devDependency y montar el componente React en modo dev en cada sitio web. Renderizar solo cuando import.meta.env.DEV es true, justo antes del cierre de <body>. Nunca llega a producción. El guard de entorno permite que el tree-shaking de Astro/Vite elimine todo el código de agentation del bundle final, sin dejar rastro en el HTML ni en el JS que recibe el usuario.