DataFlow Pro
Component Guidelines
Guía de implementación para el sistema de diseño de la plataforma de automatización de datos. Componentes listos para ingeniería con tokens, estados y criterios WCAG 2.2 AA.
01 Contexto y objetivos
DataFlow Pro es una plataforma SaaS B2B orientada a equipos de operaciones y analítica. El sistema de diseño resuelve tres problemas estructurales del producto actual: inconsistencia de variantes de botón, contraste insuficiente en formularios, y ausencia de estados de error accesibles.
02 Tokens de color
Los tokens son la única fuente de verdad para colores. Los valores hexadecimales directos en componentes están prohibidos. Todos los tokens se definen como CSS Custom Properties en :root.
:root {
/* Brand */
--color-primary: #072C2C;
--color-secondary: #FF5F03;
/* Semantic */
--color-success: #16A34A;
--color-warning: #D97706;
--color-danger: #DC2626;
/* Surface + Text */
--color-surface: #EDEADE;
--color-text: #111827;
--color-text-muted: #6B7280;
}
03 Escala tipográfica
Desktop-first. Tres familias con rol semántico claro. No mezclar roles de fuente entre sí.
04 Espaciado
Escala de 4px base, modo comfortable density. Usar siempre múltiplos de 4px. No inventar valores intermedios.
05 Botones
Intención: Los botones comunican la acción principal del contexto inmediato. Cada vista debe tener un único botón Primary visible; el resto son Secondary, Ghost o Danger.
Variantes y estados
| Regla | Nivel | Descripción |
|---|---|---|
| Hit area mínima | must | Altura mínima 36px (44px recomendado en touch). Nunca menos. |
| Un solo Primary por vista | must | Máximo 1 botón Primary visible simultáneamente. Usar Secondary para acciones secundarias. |
| Focus ring visible | must | outline: 3px solid var(--color-focus-ring) con outline-offset: 2px en :focus-visible. Nunca outline: none. |
| Label explícito | must | Los botones de icono deben incluir aria-label descriptivo. |
| Estado loading | should | Mostrar spinner + texto "Ejecutando…" durante operaciones async. Deshabilitar el botón durante loading. |
06 Inputs y formularios
Intención: Los formularios de DataFlow Pro configuran pipelines complejos. Los inputs deben ser precisos, con feedback de validación inmediato y sin ambigüedad en los labels.
Usa un nombre descriptivo que identifique fuente y destino.
Endpoint de entrada del pipeline activo.
✕ Clave API inválida. Verifica en Ajustes → Integraciones.
✓ Email verificado correctamente.
Generado automáticamente. Solo lectura.
| Regla | Nivel | Descripción |
|---|---|---|
| Label siempre visible | must | No usar solo placeholder como label. Los placeholders desaparecen al escribir. |
| Contraste de error | must | Los mensajes de error deben usar --color-danger con ratio ≥ 4.5:1 sobre fondo blanco. |
| Campo requerido | must | Marcar con asterisco (*) rojo + aria-required="true". Explicar la convención al inicio del formulario. |
| Focus ring en inputs | must | box-shadow: 0 0 0 3px rgba(255,95,3,0.15) + border-color: var(--color-secondary) en :focus. |
07 Badges de estado
Intención: Los badges comunican el estado de ejecución de pipelines de un vistazo. No usar solo color: siempre incluir texto + punto de color para accesibilidad.
| Estado | Token | Cuándo usar |
|---|---|---|
| Activo | --color-success | Pipeline ejecutándose correctamente en producción. |
| Pausado | --color-warning | Detenido manualmente; sin error activo. |
| Error | --color-danger | Última ejecución fallida. Requiere atención. |
| Completado | --color-primary | Pipeline de una sola ejecución finalizado con éxito. |
| Borrador | --color-text-muted | Configuración guardada pero no publicada. |
08 Pipeline Cards
Intención: Las tarjetas son la unidad visual principal del listado de workflows. Deben comunicar nombre, estado, descripción breve y pasos de un vistazo.
09 Tabla de datos
Intención: Las tablas son el componente de mayor densidad informativa. Deben soportar sorting, selección múltiple y acciones por fila sin saturar visualmente.
| Pipeline | Estado | Inicio | Duración | Registros | Acciones | |
|---|---|---|---|---|---|---|
| CRM → Sheets | Completado | 2026-06-16 09:02 | 1m 34s | 3.421 | ||
| Stripe → BQ | Error | 2026-06-16 06:00 | 0m 08s | 0 | ||
| CRM → Sheets | Completado | 2026-06-16 03:02 | 1m 29s | 3.401 | ||
| Email Campaign Sync | Pausado | 2026-06-14 10:15 | — | — | ||
| Sheets → Slack Alert | Activo | 2026-06-16 09:30 | 0m 04s | 12 | ||
| Mostrando 5 de 128 ejecuciones · 1 seleccionada | ||||||
10 Accesibilidad WCAG 2.2 AA
Todos los componentes deben superar los criterios WCAG 2.2 AA. La accesibilidad no es opcional ni una fase posterior: es un criterio de aceptación en cada PR.
| Criterio WCAG | Nivel | Implementación requerida | Test |
|---|---|---|---|
| 1.4.3 Contraste de texto | must | Ratio mínimo 4.5:1 para texto normal; 3:1 para texto grande (≥18px bold). | axe DevTools / Colour Contrast Analyser |
| 1.4.11 Contraste no-texto | must | Bordes de inputs, iconos funcionales y estados de componente ≥ 3:1. | Manual + axe |
| 2.1.1 Teclado | must | Toda funcionalidad accesible con Tab/Shift+Tab/Enter/Space/Escape. Sin trampas de teclado. | Manual (solo teclado) |
| 2.4.7 Focus visible | must | Focus ring visible en todos los elementos interactivos. Nunca outline:none sin reemplazo. | Tab por la página, visual |
| 2.4.11 Focus Not Obscured (AA) | must | El focus visible no debe quedar completamente oculto por elementos sticky (headers, tooltips). | Manual scroll + tab |
| 3.3.1 Error identification | must | Los errores de formulario se identifican en texto, no solo por color. Incluir aria-describedby al mensaje de error. | Screen reader (NVDA/VoiceOver) |
| 4.1.3 Status Messages | should | Los mensajes de éxito/error deben anunciarse con role="status" o aria-live="polite". | Screen reader |
11 Antipatrones y migraciones
Los patrones incorrectos del sistema actual que deben eliminarse en la migración.
outline: none; /* PROHIBIDO */
}
outline: 3px solid var(--color-focus-ring);
outline-offset: 2px;
}
color: #FF5F03;
border: 1px solid #D1D5DB;
color: var(--color-secondary);
border: 1px solid var(--color-border);
12 QA Checklist — Code Review
Ejecutar en cada PR que modifique o añada componentes UI. Toda casilla marcada como must bloquea el merge si falla.
-
Solo se usan tokens CSS (var(--color-*)) para colores. Sin valores hex directos.Tokens · must
-
Espaciados son múltiplos de 4px usando tokens --space-*.Tokens · must
-
Contraste de texto ≥ 4.5:1 verificado con axe DevTools en todos los estados del componente.Accesibilidad · must
-
Focus ring visible en :focus-visible en todos los elementos interactivos. Nunca outline:none sin reemplazo.Accesibilidad · must
-
Navegación completa por teclado (Tab, Shift+Tab, Enter, Space, Escape) probada manualmente en el flujo afectado.Accesibilidad · must
-
Los mensajes de error en formularios incluyen texto descriptivo + aria-describedby. No solo color.Accesibilidad · must
-
Botones de icono tienen aria-label descriptivo. Tablas tienen role="table" y aria-label.Accesibilidad · must
-
Existe un único botón Primary visible por vista/modal. El resto son Secondary, Ghost o Danger.Jerarquía visual · must
-
Los badges de estado incluyen texto + punto de color (no solo color como indicador único).Accesibilidad · must
-
Componentes nuevos documentados en Storybook con todas las variantes y estados requeridos.Documentación · should
-
Probado en Chrome, Firefox y Safari. Resolución mínima 1280px de ancho.Cross-browser · must
-
No se mezclan clases del sistema antiguo (.btn-old-*) con las del nuevo DS.Migración · must