Sistema de diseño futurista-profesional. Construido para equipos que escalan. Cada token, componente y regla está pensado para eliminar la inconsistencia y acelerar la entrega.
Propósito del sistema
NexaFlow AI opera en el espacio de PropTech / Operations Intelligence. Su dashboard conecta datos de propiedades, tareas y análisis predictivo. La estética debe transmitir velocidad, confianza y precisión técnica — nunca decorativismo vacío.
Este documento es la única fuente de verdad para diseñadores e ingenieros. Cada regla está anclada a un token o umbral medible; ninguna queda en términos subjetivos como "moderno" o "limpio" sin especificación concreta.
Regla maestra: la consistencia visual supera cualquier optimización local. Si tu componente necesita un valor fuera del sistema, crea primero el token.
Color Tokens
Usa siempre el nombre del token, nunca el valor hexadecimal directamente. En Tailwind: extiende el config con estas variables CSS.
Paleta Base
Tokens de Texto
| Token | Valor | Uso |
|---|---|---|
| --color-text-high | #E8F0FE | Títulos, labels primarios, valores clave |
| --color-text-mid | #94A3B8 | Texto de soporte, descripciones, cuerpo |
| --color-text-low | #475569 | Metadatos, timestamps, labels secundarios |
Escala Tipográfica
Tres familias con roles distintos. Roboto para todo el UI de datos. Audiowide exclusivamente para títulos de pantalla y el logotipo. Anonymous Pro para código y valores técnicos.
- Audiowide solo en h1/h2 de pantalla y logo
- Roboto 400 para cuerpo; 500 para énfasis
- Anonymous Pro en valores técnicos y código
- letter-spacing 0.08-0.12em en xs uppercase
- Audiowide en párrafos o labels de formulario
- Roboto con weight 300 en texto menor a 14px
- Más de 3 pesos tipográficos en una pantalla
- Texto body en Anonymous Pro
Escala de Espaciado
Base de 4px. Todos los márgenes, paddings y gaps deben ser múltiplos de la escala. Nunca usar valores arbitrarios como 10px, 15px o 20px.
Botones
El botón es el componente más usado del sistema. Existen cuatro variantes semánticas; la elección debe basarse en la importancia de la acción, no en preferencias estéticas.
Anatomía del botón
| Propiedad | Primary | Secondary | Ghost |
|---|---|---|---|
| Background | --color-primary | transparent | transparent |
| Border | --color-primary | --color-border-strong | transparent |
| Padding | 8px 16px | 8px 16px | 8px 16px |
| Focus ring | 3px offset, --primary 0.15 alpha | 3px offset, --primary 0.15 alpha | 3px offset, --primary 0.15 alpha |
| Disabled opacity | 0.38 | 0.38 | 0.38 |
Una pantalla debe tener un máximo de 1 botón primary visible a la vez. Si necesitas dos CTA primarios, reconsideras la jerarquía de acciones.
Formularios e Inputs
Estados requeridos
| Estado | Border | Sombra | Trigger |
|---|---|---|---|
| default | --color-border | none | Estado inicial |
| focus | --color-primary | 0 0 0 3px rgba(primary, 0.15) | :focus-visible |
| error | --color-danger | 0 0 0 3px rgba(danger, 0.12) | Validación fallida |
| success | --color-success | none | Validación ok |
Badges y Tags
Comunican estado semántico. La variante se elige por su significado, no por colores favoritos.
| Variante | Uso semántico | Must NOT usar para |
|---|---|---|
| primary | Estado activo, en progreso, seleccionado | Decoración, sin valor semántico |
| danger | Error, bloqueado, crítico | Urgente o importante (usar warning) |
| success | Completado, verificado, activo | Progreso parcial |
DataTable
La tabla es el componente central del dashboard de NexaFlow. Reglas de anatomía obligatorias: cabecera fija, fila de hover, estado vacío y paginación.
- th en uppercase xs mono + letter-spacing
- Hover row con bg-elevated completo
- Alinear números a la derecha
- Estado vacío con ilustración + CTA
- Borders en todas las celdas (solo row-bottom)
- Múltiples colores de fondo por fila
- Texto truncado sin tooltip
- Columna de acciones sin alineación right
Reglas Do / Don't
- Usar tokens semánticos, no hex directos
- Mantener jerarquía visual: 1 primary CTA por pantalla
- Focus ring visible en todos los elementos interactivos
- Escala de espaciado 4px en todo el sistema
- Definir estados vacíos con contenido accionable
- Texto de error con posición predecible (debajo del campo)
- Texto gris sobre fondo oscuro sin verificar ratio AA
- Espaciado arbitrario (10px, 15px, 20px)
- Ocultar focus ring con outline: none
- Usar Audiowide en cuerpo de texto
- Múltiples botones primary en la misma zona visual
- Bordes decorativos sin función semántica
Anti-Patrones y Migraciones
Anti-patrón 1: Botón sin jerarquía
El usuario no sabe qué acción es la principal. El azul saturado en fondo oscuro pierde contraste.
Un primary CTA, acciones secundarias con jerarquía decreciente. Escaneo visual inmediato.
Anti-patrón 2: Tokens en línea
Migración: cualquier componente existente con valores hex directos debe ser refactorizado antes del merge a main en v2.0. El PR checker rechaza archivos que contengan #3B82F6 fuera de globals.css.
Requisitos WCAG 2.2 AA
Cada criterio es testable en code review. No son recomendaciones, son blockers de merge.
| Criterio | Umbral | Cómo verificar |
|---|---|---|
| Contraste texto normal | ≥ 4.5:1 | axe DevTools / Storybook a11y addon |
| Contraste texto grande (≥18px bold) | ≥ 3:1 | Figma Color Contrast plugin |
| Focus ring visible | ≥ 3px offset | Tab navigation manual en cada PR |
| Área de clic mínima | ≥ 44×44px | Chrome DevTools grid inspect |
| Atributo aria-label en icon buttons | obligatorio | ESLint jsx-a11y |
| Loading state anunciado | aria-busy | aria-busy="true" en botón loading |
QA Checklist
Ejecutar en cada PR que modifique UI. Los ítems con badge blocker detienen el merge.
-
Tokens de colorNo hay valores hex directos fuera de globals.css
-
Contraste AATodos los textos superan ratio 4.5:1 (axe)
-
Focus ringTab key navega todos los elementos interactivos
-
EspaciadoNingún valor de margin/padding fuera de escala 4px
-
ResponsiveBreakpoints 320px / 768px / 1280px testeados
-
Estados vacíosTablas y listas tienen empty state con CTA
-
Errores de formMensaje de error bajo el campo, no en toast solo
-
1 Primary CTAMáximo 1 btn-primary visible por zona de acción
-
TipografíaAudiowide solo en h1/h2; Roboto en resto
-
Loading statesBotones con aria-busy y spinner visible