Antes de meterle a sprint 1 etapa 4 y 5

2026-05-16 13:46:27 -03:00
parent 0ef75aa9a9
commit f9a008bce5
14 changed files with 666 additions and 8 deletions
--- a/DESIGN_SYSTEM.md
+++ b/DESIGN_SYSTEM.md
@@ -0,0 +1,330 @@
+# InQ ROI — Sistema de Diseño
+
+> Documento de referencia visual para Sprint 2+.
+> Fuente de verdad para la paleta, tipografía y componentes.
+> Actualizar en cada sprint que modifique la identidad visual.
+
+---
+
+## 1. Identidad de Marca
+
+### Nombre del producto
+**InQ ROI** — herramienta interna de InQuality para cuantificación de ROI de automatización.
+
+### Regla de ortografía (NO NEGOCIABLE)
+```
+✅ InQ         ← I mayúscula, n minúscula, Q mayúscula
+✅ InQuality   ← nombre completo
+❌ INQ / Inq / inq / inQ  ← cualquiera es bug
+```
+
+### Tagline en footers PDF
+`"Powered by InQuality"` — obligatorio en todos los footers de PDF.
+
+---
+
+## 2. Paleta Cromática
+
+### 2.1 InQ Orange — Color protagonista
+
+| Token Tailwind | CSS Var | Hex | HSL | Uso |
+|---|---|---|---|---|
+| `bg-inq-orange` | `--inq-orange` | `#F59845` | 28° 90% 62% | Principal: logo, KPIs hero, CTAs primarios |
+| `bg-inq-orange-dark` | `--inq-orange-dark` | `#B45309` | 34° 93% 37% | Texto sobre fondos claros, hover de CTAs |
+| `bg-inq-orange-light` | `--inq-orange-light` | `#FEF3E2` | 36° 95% 88% | Fondos de KPI cards |
+| `bg-inq-orange-lighter` | `--inq-orange-lighter` | `#FFF8ED` | 36° 100% 94% | Fondos de banner narrativo, hover sutiles |
+
+### 2.2 InQ Magenta — Gradiente identidad
+
+| Token Tailwind | CSS Var | Hex | Uso |
+|---|---|---|---|
+| `bg-inq-magenta` | `--inq-magenta` | `#ED3E8F` | Segundo color del gradiente identidad |
+
+#### Gradiente identidad
+```css
+background: linear-gradient(135deg, #F59845 0%, #ED3E8F 100%);
+```
+
+**Uso exclusivo:** KPI Hero "Ahorro proyectado" en PDF y web. NUNCA en bordes, separadores ni fondos secundarios.
+
+### 2.3 Semánticos
+
+| Token Tailwind | CSS Var | Hex | Uso |
+|---|---|---|---|
+| `bg-success` | `--color-success` | `#16A34A` | Ahorros positivos, payback alcanzado |
+| `bg-success-light` | `--color-success-light` | `#F0FDF4` | Fondos de mensajes positivos |
+| `bg-warning` | `--color-warning` | `#F59E0B` | Advertencias, sección transparencia |
+| `bg-warning-bg` | `--color-warning-bg` | `#FFFBEB` | Fondo de sección transparencia |
+| `bg-destructive` / `--color-danger` | — | `#EF4444` | Costos altos, valores negativos |
+| `--color-danger-light` | — | `#FEE2E2` | Fondos de heatmap alto costo |
+
+### 2.4 Heatmap — Paleta saturada (FIJA hasta Sprint 3-4)
+
+| Token Tailwind | Hex | RGB | Uso |
+|---|---|---|---|
+| `bg-heatmap-low` | `#10B981` | (16, 185, 129) | Actividades de bajo costo |
+| `bg-heatmap-mid` | `#F59E0B` | (245, 158, 11) | Actividades de costo medio |
+| `bg-heatmap-high` | `#EF4444` | (239, 68, 68) | Actividades de alto costo |
+
+#### Decisión sobre paleta de heatmap
+
+**Se mantiene saturada** (verde-ámbar-rojo) en lugar de la variante pastel del brief por dos razones:
+
+1. **Tests E2E calibrados**: los análisis de píxeles del heatmap (`export-pdf.spec.ts`, `validate-dod-etapa4.spec.ts`) tienen umbrales calibrados para estos colores. Cambiar la paleta requiere recalibrar todos esos umbrales.
+
+2. **Visibilidad en pantallas grandes**: el producto se usa en talleres y charlas InQuality proyectadas en pantalla. Los colores saturados mantienen contraste a distancia. Los pasteles se "lavan" a 3+ metros.
+
+**Revisión programada**: Sprint 3-4 con feedback real de uso en talleres.
+
+**Invariante crítica**: los valores de `tailwind.config.js` `heatmap.*` DEBEN coincidir con las constantes `HEATMAP_LOW/MID/HIGH` en `src/lib/colors.ts`. Si se modifica uno, debe actualizarse el otro.
+
+### 2.5 Neutrales
+
+| Hex | Tailwind equivalente | Uso |
+|---|---|---|
+| `#0F172A` | `slate-900` | Títulos, números importantes |
+| `#475569` | `slate-600` | Texto del cuerpo |
+| `#64748B` | `slate-500` | Labels, metadatos |
+| `#94A3B8` | `slate-400` | Placeholders, texto muy secundario |
+| `#E2E8F0` | `slate-200` | Bordes generales |
+| `#F1F5F9` | `slate-100` | Separadores sutiles |
+| `#F8FAFC` | `slate-50` | Fondo de la app, canvas BPMN |
+
+### 2.6 Colores que NO usar
+
+```
+❌ #572FA2  Morado primario de CONCILIA — marca hermana, no mezclar
+❌ #CB1889  Magenta de CONCILIA
+❌ azul shadcn por defecto (221.2 83.2% 53.3%) — reemplazado por InQ orange
+```
+
+---
+
+## 3. Tipografía
+
+### 3.1 Familias
+
+```css
+/* Primaria — web app y body de PDFs */
+font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
+
+/* Mono — números en tablas, datos financieros */
+font-family: 'JetBrains Mono', 'SF Mono', Consolas, monospace;
+```
+
+Tailwind: `font-sans` / `font-mono`
+
+### 3.2 Escala PDF
+
+| Elemento | Tamaño | Peso | Tracking |
+|---|---|---|---|
+| Logo "InQ ROI" en header | 22px | 700 | −0.8px |
+| Título de sección | 16px | 500 | normal |
+| KPI Hero (cifra) | 30px | 700 | −1px |
+| KPI secundario (cifra) | 16px | 700 | normal |
+| Body text | 11px | 400 | normal |
+| Labels en cards | 8px | 500 | 1px uppercase |
+| Tabla header | 10px | 500 | normal |
+| Tabla body | 10px | 400 | normal |
+| Footer | 9px | 400 | normal |
+
+### 3.3 Escala Web App
+
+| Elemento | Tamaño |
+|---|---|
+| Logo header | 18px / 700 |
+| Page title | 16px / 500 |
+| KPI Hero | 28px / 700 |
+| KPI secundario | 16px / 700 |
+| Nav / Tabs | 12px / 400-500 |
+| Body | 12-13px / 400 |
+| Labels en panels | 10-11px / 400-500 |
+
+---
+
+## 4. Componentes
+
+### 4.1 KPI Hero (gradiente naranja → magenta)
+
+```
+Fondo:        linear-gradient(135deg, #F59845 0%, #ED3E8F 100%)
+Padding:      16-18px
+Border-radius: 6-8px
+Label:        9-10px / uppercase / letter-spacing 1.2px / white opacity 0.9
+Cifra:        28-30px / 700 / letter-spacing −1px / white
+Subtítulo:    10-11px / white opacity 0.85
+```
+
+Uso: el KPI "Ahorro proyectado a N años" — el más importante del reporte ROI.
+
+### 4.2 KPI Card (secundario, fondo naranja claro)
+
+```
+Fondo:        #FEF3E2 (inq-orange-light)
+Padding:      10px 12px
+Border-radius: 6px
+Label:        8px / 500 / letter-spacing 1px / color #92400E / uppercase
+Cifra:        16px / 700 / color #0F172A
+Delta:        10px / 500 / color #B45309
+```
+
+### 4.3 Banner narrativo (resumen ejecutivo)
+
+```
+Fondo:        #FFF8ED (inq-orange-lighter)
+Border-left:  3px solid #F59845
+Padding:      10-12px 14px
+Border-radius: 0 4px 4px 0
+Texto:        11px / 400 / line-height 1.55 / color #475569
+```
+
+### 4.4 Sección Transparencia Metodológica
+
+```
+Fondo:        #FFFBEB (warning-bg)
+Border:       0.5px solid #F59E0B
+Padding:      12px 14px
+Border-radius: 6px
+Título:       11px / 500 / color #92400E / con ícono ⚠
+Texto:        10px / 400 / line-height 1.6 / color #78350F
+```
+
+4 condiciones que activan la sección:
+1. Actividades `automatable=true` con `automatedCostFixed=0` y `automatedTimeMinutes=0`
+2. `automationInvestment=0`
+3. `roiAnnualPercent > 1000` (finito)
+4. (reservado para futuras reglas)
+
+### 4.5 Tabla comparativa PDF
+
+```
+Header row:
+  Fondo:       #FFF8ED
+  Border-bottom: 1px solid #F59845
+  Texto:       10px / 500 / #92400E
+
+Body row — automatizable:
+  Fondo:       white
+
+Body row — no automatizable:
+  Fondo:       #F8FAFC
+  Texto:       color #64748B (más tenue)
+
+Total row:
+  Fondo:       #FFF8ED
+  Border-top:  1.5px solid #F59845
+  Texto:       10px / 500 / #0F172A
+```
+
+### 4.6 Header PDF
+
+```
+Layout:       flex justify-between
+Border-bottom: 3px solid #F59845 (pág. 1) / 2px (otras)
+Padding-bottom: 10-12px
+Margin-bottom: 14-16px
+
+Izquierda:
+  "InQ ROI"  18-22px / 700 / #F59845
+  Tagline:   9px / letter-spacing 1.5px / #94A3B8 (solo pág. 1)
+
+Derecha:
+  "UN PRODUCTO DE"  9px / letter-spacing 1px / #94A3B8
+  "InQ"             16px / 700 / #475569
+  "InQuality"       9px / #64748B
+```
+
+### 4.7 Footer PDF
+
+```
+Position:     absolute bottom 14-16mm
+Padding-top:  6-8px
+Border-top:   0.5px solid #E2E8F0
+Layout:       flex justify-between
+Font:         9px / 400 / #94A3B8
+
+Izquierda:   "InQ ROI" bold #F59845 " · Powered by InQuality · " cliente · fecha
+Derecha:     "Página X de Y"
+```
+
+### 4.8 Badge ⚡ (Automatizable)
+
+#### En canvas BPMN overlay
+```
+Diámetro:    14px
+Fondo:       #F59845 (naranja sólido)
+Border:      1.5px solid white
+Posición:    { top: -8, left: nodeWidth - 12 }
+Símbolo:     ⚡ blanco 8px
+```
+
+Nota: en Sprint 1 el badge usa fondo `#fffbeb` (ámbar-50) con ícono ámbar. La migración a naranja sólido se hace en **Etapa 9** de Sprint 1.5.
+
+#### En tablas y leyendas
+```
+Diámetro:    14px inline
+Fondo:       #F59845
+Color:       white
+```
+
+### 4.9 Layout híbrido de PDFs (portrait + landscape)
+
+Los PDFs combinan orientaciones por página:
+
+- **Páginas SIN diagrama**: A4 vertical (210×297mm) — texto, tablas, KPIs
+- **Página DEL diagrama BPMN**: A4 horizontal (297×210mm) — para que el diagrama ocupe espacio real
+
+Implementación jsPDF: `doc.addPage([297, 210], 'landscape')`
+
+---
+
+## 5. Tokens en código
+
+### Web (Tailwind)
+
+```tsx
+// Colores de marca
+<div className="bg-inq-orange">          // #F59845
+<div className="bg-inq-orange-dark">     // #B45309
+<div className="bg-inq-orange-light">    // #FEF3E2
+<div className="text-inq-orange">        // texto naranja
+<div className="border-inq-orange">      // borde naranja
+
+// Gradiente identidad (como style prop — Tailwind no soporta gradientes dinámicos)
+<div style={{ background: 'linear-gradient(135deg, #F59845 0%, #ED3E8F 100%)' }}>
+
+// Semánticos
+<div className="bg-success text-white">  // #16A34A
+<div className="bg-warning-bg">          // #FFFBEB
+```
+
+### PDF (jsPDF)
+
+```typescript
+// Constante en pdf-sections.ts (a migrar en Etapas 4-8)
+const PDF_ORANGE: [number, number, number] = [245, 152, 69]  // #F59845
+const PDF_ORANGE_LIGHT: [number, number, number] = [254, 243, 226]  // #FEF3E2
+const PDF_MAGENTA: [number, number, number] = [237, 62, 143]  // #ED3E8F
+
+// Gradiente en jsPDF se simula con pasos (ver pdf-sections-roi.ts)
+```
+
+---
+
+## 6. Reglas de uso — DO / DON'T
+
+### DO ✅
+- Usar `bg-primary` / `text-primary` para todos los CTAs — hereda el naranja de `--primary`
+- Usar gradiente identidad en exactamente 1 KPI Hero por página/vista
+- Usar `font-mono` para todos los números financieros
+- Escribir siempre **InQ** con I-n-Q
+
+### DON'T ❌
+- Usar `bg-blue-*` donde debería ir naranja InQ
+- Aplicar el gradiente en más de un elemento por vista
+- Usar colores de CONCILIA (`#572FA2`, `#CB1889`)
+- Cambiar los colores del heatmap sin recalibrar los tests E2E
+
+---
+
+*Actualizado: Sprint 1.5 Etapa 1 — 2026-05-16*