feat(sprint-1-5): cierre Etapa 2 - formatPayback + fixes de marca

[
2026-05-16 19:26:19 -03:00
parent f9a008bce5
commit eaaac88fc3
16 changed files with 1626 additions and 55 deletions
--- a/sprints/sprint-1-5/SPRINT_1_5_BRIEF_REDISENIO_VISUAL.md
+++ b/sprints/sprint-1-5/SPRINT_1_5_BRIEF_REDISENIO_VISUAL.md
@@ -0,0 +1,852 @@
+# Sprint 1.5 — Brief de Rediseño Visual
+
+> **Propósito:** rediseñar la identidad visual del producto (PDFs + Web App) con manual de marca InQ ROI antes del cierre de Sprint 1. No agrega nuevas features funcionales; refina presentación, identidad y polish.
+
+> **Justificación:** los PDFs y la web app actuales son funcionales pero genéricos. El producto va a ser usado en pre-venta, talleres y charlas de InQuality, requiere identidad sólida desde el inicio. La iteración visual es 5–10× más barata ahora que después.
+
+---
+
+## 0. Contexto crítico
+
+Este producto es **una herramienta de InQuality**, no un producto independiente. Se construye con identidad propia (color naranja InQ) pero parte de la familia visual de productos InQuality (junto con CONCILIA, que usa morado). Lleva la marca "Powered by InQuality" en footers.
+
+**Regla NO NEGOCIABLE de marca:** la versión corta de InQuality SIEMPRE se escribe **InQ** — I mayúscula, n minúscula, Q mayúscula. Cualquier desviación (InQ, INQ, Inq, inQ) es bug.
+
+---
+
+## 1. Manual de marca InQ ROI
+
+### 1.1 Paleta cromática
+
+#### Color protagonista — Naranja InQ
+| Token CSS | Hex | Uso |
+|---|---|---|
+| `--inq-orange` | `#F59845` | Principal. Logo, KPIs hero, headers, CTAs primarios |
+| `--inq-orange-dark` | `#B45309` | Texto destacado sobre fondos claros, hover de CTAs |
+| `--inq-orange-light` | `#FEF3E2` | Fondos de KPI cards, fondos sutiles |
+| `--inq-orange-lighter` | `#FFF8ED` | Fondos de banner narrativo, hover states muy sutiles |
+
+#### Gradiente hero (sólo para KPIs hero y banners principales)
+```css
+background: linear-gradient(135deg, #F59845 0%, #ED3E8F 100%);
+```
+
+Donde `#ED3E8F` es el magenta InQ. Este gradiente representa la familia visual InQuality y se usa SOLO en:
+- KPI hero "Ahorro proyectado a 3 años" (PDF y web)
+- Carátulas o banners principales (si aparecen)
+- NUNCA en bordes, separadores, fondos secundarios
+
+#### Colores semánticos
+| Token CSS | Hex | Uso |
+|---|---|---|
+| `--color-success` | `#16A34A` | Ahorros positivos, "óptimo" |
+| `--color-success-light` | `#F0FDF4` | Fondos de mensajes positivos |
+| `--color-warning` | `#F59E0B` | Advertencias, sección transparencia |
+| `--color-warning-bg` | `#FFFBEB` | Fondos de advertencia |
+| `--color-danger` | `#EF4444` | Costos altos, errores |
+| `--color-danger-light` | `#FEE2E2` | Fondos de heatmap (alto costo) |
+
+#### Heatmap (gradient de costo)
+```css
+/* Bajo → Medio → Alto */
+background: linear-gradient(to right, #BBF7D0, #FED7AA, #FECACA);
+```
+
+#### Neutrales (tipografía y bordes)
+| Token CSS | Hex | Uso |
+|---|---|---|
+| `--text-primary` | `#0F172A` | Títulos, números importantes |
+| `--text-secondary` | `#475569` | Texto del cuerpo |
+| `--text-tertiary` | `#64748B` | Labels, metadatos |
+| `--text-disabled` | `#94A3B8` | Placeholders, texto muy secundario |
+| `--border-primary` | `#E2E8F0` | Bordes generales |
+| `--border-light` | `#F1F5F9` | Separadores sutiles |
+| `--bg-app` | `#F8FAFC` | Fondo de la app |
+| `--bg-card` | `#FAFBFC` | Fondo de tarjetas secundarias |
+
+### 1.2 Tipografía
+
+#### Familia
+- **Primaria** (web app y PDFs): system-ui stack, con fallback a Roboto embebido en PDFs.
+  ```css
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
+  ```
+- **Mono** (números en tablas, datos financieros): `'JetBrains Mono', 'SF Mono', Consolas, monospace`.
+
+#### Jerarquía de tamaños (PDF)
+| Elemento | Tamaño | Peso | Tracking |
+|---|---|---|---|
+| Logo "InQ ROI" en header | 22px | 700 | -0.8px |
+| Título sección (página title) | 16px | 500 | normal |
+| KPI Hero (cifra grande) | 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 |
+
+#### Jerarquía de tamaños (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 |
+
+### 1.3 Reglas de uso del logo "InQ ROI"
+
+- **Tipografía:** sans-serif bold con tracking apretado (-0.5px a -0.8px)
+- **Color por defecto:** `#F59845`
+- **Color sobre gradiente o fondos oscuros:** blanco
+- **Posición en PDFs:** esquina superior derecha del header de cada página
+- **Posición en Web App:** esquina superior izquierda del topbar
+- **Mínimo aire alrededor:** 16px en todas direcciones
+- **Aclaración "Powered by InQuality":** SIEMPRE en footer, no en header
+
+### 1.4 Iconografía
+
+- **Sistema:** Lucide React (ya instalado)
+- **Tamaños estándar:** 12px, 14px, 16px, 20px, 24px
+- **Color por defecto:** hereda del contexto (`currentColor`)
+- **Ícono "Automatizable" (⚡):** símbolo emoji ⚡ por ahora. Cambiar a `<Bot />` de Lucide en Sprint 2-3 (anotar en TODO.md)
+- **Badge automatizable:** círculo `#F59845` con ⚡ blanco centrado, tamaño 14-22px según contexto
+
+---
+
+## 2. Sistema de diseño — Componentes clave
+
+### 2.1 KPI Card (cifra grande)
+
+```
+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 (verde-orange-dark)
+```
+
+### 2.2 KPI Hero (gradiente)
+
+```
+Fondo:       linear-gradient(135deg, #F59845 0%, #ED3E8F 100%)
+Padding:     16-18px
+Border-radius: 6-8px
+Label:       9-10px / opacity 0.9 / letter-spacing 1.2px / white
+Cifra:       28-30px / 700 / letter-spacing -1px / white
+Subtítulo:   10-11px / opacity 0.85 / white
+```
+
+### 2.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
+```
+
+### 2.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
+```
+
+### 2.5 Tabla comparativa
+
+```
+Header row:
+  Fondo:       #FFF8ED
+  Border-bottom: 1px solid #F59845
+  Padding:     8px 6px
+  Texto:       10px / 500 / color #92400E
+
+Body row (default):
+  Fondo:       white
+  Border-bottom: 0.5px solid #E2E8F0
+  Padding:     8px 6px
+  Texto:       10px / 400 / color #0F172A
+  Números:     font-family mono
+
+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 / color #0F172A
+```
+
+### 2.6 Header de página PDF
+
+```
+Layout:      flex justify-between
+Border-bottom: 3px solid #F59845 (página 1) / 2px (otras páginas)
+Padding-bottom: 10-12px
+Margin-bottom: 14-16px
+
+Izquierda:
+  Logo "InQ ROI": 18-22px / 700 / #F59845
+  Tagline (página 1): 9px / letter-spacing 1.5px / #94A3B8
+
+Derecha:
+  Label "UN PRODUCTO DE": 9px / letter-spacing 1px / #94A3B8
+  "InQ": 16px / 700 / #475569
+  "InQuality": 9px / #64748B
+```
+
+### 2.7 Footer de página PDF
+
+```
+Position:    absolute bottom 14-16px
+Padding-top: 6-8px
+Border-top:  0.5px solid #E2E8F0
+Layout:      flex justify-between
+Font:        9px / 400 / #94A3B8
+
+Izquierda:
+  "InQ ROI" en bold #F59845
+  " · Powered by InQuality · "
+  Nombre cliente · fecha
+
+Derecha:
+  "Página X de Y"
+```
+
+### 2.8 Badge "Automatizable" (⚡)
+
+#### En canvas BPMN (overlay)
+```
+Tamaño:      14px diameter
+Fondo:       #F59845
+Border:      1.5px solid white
+Posición:    top: -8, left: nodeWidth - 12 (ver Etapa 2 - cambio de bpmn-js right)
+Símbolo ⚡:   white, 8px, font-weight 700
+```
+
+#### En tabla
+```
+Tamaño:      14px diameter inline
+Fondo:       #F59845
+Color:       white
+```
+
+#### En leyenda
+```
+Tamaño:      14px diameter
+Mismo estilo que en tabla
+```
+
+---
+
+## 3. Rediseño de PDFs
+
+### 3.1 Decisión arquitectónica: orientación híbrida
+
+Los PDFs con diagrama BPMN tendrán **layout híbrido portrait + landscape**:
+
+- **Páginas SIN diagrama:** vertical A4 (portrait)
+- **Página DEL diagrama BPMN:** horizontal A4 (landscape) — para que el diagrama tenga espacio real
+
+Esto es bloqueante: jsPDF soporta página por página con orientación individual. Implementar usando `doc.addPage([width, height], 'landscape')` para la página del diagrama.
+
+### 3.2 PDF de Comparación + ROI (4 páginas)
+
+#### Página 1 — Resumen ejecutivo (vertical)
+
+Reemplaza la carátula. Header denso que incluye toda la metadata.
+
+```
+Header (con border-bottom 3px solid #F59845):
+  - Logo InQ ROI a la izquierda
+  - "UN PRODUCTO DE / InQ / InQuality" a la derecha
+
+Strip de metadata (grid 2fr 1fr 1fr en fondo #FAFBFC):
+  - Proceso: Originación de créditos personales
+  - Cliente: Banco Atlántico S.A.
+  - Fecha: 15 mayo 2026
+
+Banner narrativo (#FFF8ED con border-left naranja):
+  Resumen ejecutivo: Automatización de N actividades sobre proceso de M etapas.
+  Frecuencia X/año, horizonte Y años, inversión USD Z.
+
+KPI Hero (gradiente naranja → magenta):
+  AHORRO PROYECTADO A 3 AÑOS
+  USD 192.400 — neto de inversión
+  Recuperás 2,4× la inversión en el período
+
+KPIs secundarios (grid 2x2):
+  - AHORRO POR EJECUCIÓN: USD 18,16 — ↓ 38%
+  - AHORRO ANUAL: USD 90.800
+  - PAYBACK: 10,6 meses
+  - ROI ANUAL: 114%
+
+Top 3 ahorros (caja con border #E2E8F0):
+  Header: "[3] Top actividades con mayor ahorro"
+  3 barras horizontales con %, monto, label
+
+Trayectoria del ahorro (caja con border #E2E8F0):
+  Gráfico SVG nativo en jsPDF con:
+    - Área negativa (antes del payback) en #FEE2E2
+    - Área positiva (después) en #FED7AA
+    - Línea principal #F59845
+    - Marker vertical en mes de payback
+    - Labels eje X: 0 / Año 1 / Año 2 / Año 3
+    - Valor final en esquina superior derecha
+  IMPORTANTE: dibujado con jsPDF nativo, NO captura html2canvas
+  (los charts ECharts en imagen quedan borrosos, lo verificamos en MVP)
+
+Footer (absolute bottom):
+  "InQ ROI · Powered by InQuality · Banco Atlántico · 15 may 2026"
+  "Página 1 de 4"
+```
+
+#### Página 2 — Diagrama BPMN (horizontal)
+
+```
+Orientación: landscape A4
+
+Header (border-bottom 2px solid #F59845):
+  - Logo InQ ROI + título "MAPA DE CALOR · ESCENARIO ACTUAL"
+  - "Originación de créditos personales"
+  - Costo total a la derecha
+
+Canvas del diagrama:
+  - Background #FAFBFC
+  - Border 0.5px #E2E8F0
+  - Border-radius 6px
+  - Padding 18px
+  - Altura ~400px (toma casi toda la página)
+  - El diagrama BPMN ocupa TODO el ancho disponible
+  - Embebido como JPEG vía html2canvas
+  - Badge ⚡ #F59845 sobre los nodos automatizables
+
+Leyenda al pie:
+  - Heatmap gradient: bajo → alto
+  - Badge ⚡: marcado como automatizable
+
+Footer (modificado para landscape):
+  Mismo formato pero ajustado al ancho horizontal
+```
+
+#### Página 3 — Comparación por actividad (vertical)
+
+```
+Header:
+  - Logo InQ ROI
+  - "COMPARACIÓN ACTIVIDAD POR ACTIVIDAD"
+  - "Detalle de costos: actual vs. automatizado"
+
+Texto introductorio:
+  "Las actividades marcadas con [⚡] son candidatas a automatización..."
+
+Tabla autotable (jsPDF-autotable):
+  Columnas: Actividad | Costo actual | Costo auto. | Ahorro | % | Prob.
+  Header con fondo #FFF8ED y border-bottom #F59845
+  Filas automatizables: fondo blanco
+  Filas no-automatizables: fondo #F8FAFC, texto #64748B
+  Total row: fondo #FFF8ED, border-top 1.5px #F59845
+
+Nota:
+  "Tabla muestra X de Y actividades..."
+
+Footer estándar
+```
+
+#### Página 4 — Análisis y metodología (vertical)
+
+```
+Header:
+  "CONTEXTO DEL ANÁLISIS"
+  "Composición del ahorro y metodología"
+
+Sección: Origen del ahorro
+  Texto: "El N% del ahorro proyectado proviene de la automatización de..."
+  3 barras horizontales con el desglose
+
+Sección: Metodología de cálculo
+  Caja gris (#F8FAFC):
+    - Costo por ejecución (fórmula)
+    - Ahorro anual (fórmula)
+    - Payback (fórmula)
+    - ROI anualizado (fórmula)
+
+Sección: Supuestos del análisis
+  Caja ámbar (warning):
+    Texto sobre limitaciones y supuestos
+
+Sección: Transparencia metodológica (CONDICIONAL)
+  Solo si TransparencySection detecta casos (los 4 ya implementados):
+    - Caso 1: actividades automatizables con costo cero
+    - Caso 2: inversión cero
+    - Caso 3: ROI > 1000%
+    - Caso 4: payback < 1 mes con inversión 0
+  Mismo estilo de caja ámbar
+
+Sección: Próximos pasos sugeridos (opcional, hardcoded por ahora)
+  3-4 puntos de validación recomendada
+
+Footer estándar
+```
+
+### 3.3 PDFs de Actual y Automatizado (3 páginas cada uno)
+
+Los PDFs por escenario individual mantienen estructura similar pero adaptada:
+
+```
+Página 1 (vertical):
+  Header
+  Strip de metadata
+  KPIs principales (Costo total, Costo directo/Overhead, Tiempo, Actividades)
+  Top 3 actividades por costo
+  Footer
+
+Página 2 (horizontal):
+  Diagrama BPMN con heatmap embebido
+  Leyenda
+
+Página 3 (vertical):
+  Tabla de costos por actividad
+  Nota metodológica
+  Footer
+```
+
+### 3.4 Formato de Payback (regla global)
+
+Implementar en un helper compartido entre web y PDF:
+
+```typescript
+function formatPayback(months: number): string {
+  if (!isFinite(months)) return "No recupera en horizonte";
+  if (months === 0) return "Inmediato";
+  if (months < 0.1) return "< 1 día";
+  if (months < 1) return `< 1 mes (${months.toFixed(2)} meses)`;
+  if (months < 12) return `${months.toFixed(1)} meses`;
+  if (months < 24) {
+    const years = (months / 12).toFixed(1);
+    return `${months.toFixed(1)} meses (~${years} años)`;
+  }
+  return `${(months / 12).toFixed(1)} años`;
+}
+```
+
+Tests:
+- 0 → "Inmediato"
+- 0.05 → "< 1 día"
+- 0.5 → "< 1 mes (0.50 meses)"
+- 6 → "6.0 meses"
+- 15 → "15.0 meses (~1.3 años)"
+- 30 → "2.5 años"
+- Infinity → "No recupera en horizonte"
+
+---
+
+## 4. Rediseño Web App
+
+### 4.1 Topbar global
+
+```
+Background:  white
+Border-bottom: 1px solid #E2E8F0
+Padding:     12px 20px
+Layout:      flex justify-between
+
+Izquierda:
+  Logo "InQ ROI" 18px / 700 / #F59845
+  Spacer 24px
+  Nav links:
+    - Workspace (activo: fondo #FFF8ED, texto #F59845, font-weight 500)
+    - Reporte
+    - Recursos
+  Cada link: padding 6px 12px, border-radius 4px
+
+Derecha:
+  Botón secundario "Exportar PDF" (white, border #E2E8F0)
+  Botón primario "Simular →" (background #F59845, color white)
+```
+
+### 4.2 Workspace (BpmnCanvas + ActivityPanel)
+
+```
+Layout:      flex, height calc(100vh - topbar)
+
+Canvas izquierdo (flex 1):
+  Background:  #FAFBFC
+  Padding:     20px
+  Border-right: 1px solid #E2E8F0
+
+  Diagrama BPMN:
+    - Estilos por defecto de bpmn-js
+    - Actividad seleccionada: fondo #FFF8ED, border 2px #F59845
+    - Badges ⚡ en automatizables: círculo #F59845, ⚡ blanco
+    - Posición badge: top: -8, left: width - 12
+
+  Leyenda flotante (bottom-left):
+    Background white, border 0.5px #E2E8F0, radius 6px
+    Padding 8px 12px
+    Contenido: "N actividades automatizables" con icono
+
+Panel derecho (width 280-320px):
+  Background:  white
+  Padding:     16px 18px
+  Overflow:    auto
+
+  Header del panel:
+    Badge ⚡ + nombre actividad + "Actividad seleccionada"
+    Border-bottom 1px #E2E8F0
+    Padding-bottom 12px
+
+  Sección "COSTO ACTUAL":
+    Label 10px / 500 / letter-spacing 1px / #94A3B8
+    Inputs: border #E2E8F0, padding 6px 10px, bg #F8FAFC
+
+  Sección "AUTOMATIZACIÓN" (caja destacada):
+    Background:  #FFF8ED
+    Border:      1px solid #F59845
+    Padding:     12px
+    Border-radius: 6px
+
+    Header con título y switch:
+      "AUTOMATIZACIÓN" 11px / 500 / #92400E
+      Switch: 30x16px, background #F59845 cuando ON
+
+    Inputs:
+      border #F59845, background white, color #0F172A
+
+  Helper de ahorro estimado (cuando aplica):
+    Background:  #F0FDF4
+    Border-left: 2px solid #16A34A
+    Padding:     8px 10px
+    Texto:       10px / color #15803D
+    Texto: "Ahorro estimado: USD X por ejecución (Y%)"
+```
+
+### 4.3 Reporte ROI (tab Comparación + ROI)
+
+```
+Page header:
+  Título "Nombre del proceso"
+  Subtítulo "Cliente · Simulado el ..."
+
+Tabs:
+  3 tabs horizontales con border-bottom-color en activo
+  Activo: border-bottom 2px #F59845, texto #F59845 / 500
+  Inactivo: texto #64748B
+
+Contenido tab "Comparación + ROI":
+
+  KPI Hero:
+    Mismo estilo que PDF — gradient naranja → magenta
+    Margin-bottom 12px
+
+  KPIs secundarios (grid 4 columnas):
+    Mismo estilo que PDF
+    Gap 8px
+
+  Gráficos (grid 2 columnas):
+    Trayectoria del ahorro: chart con líneas y marker
+    Top 3 ahorros: barras horizontales
+
+  Tabla comparativa completa abajo:
+    Misma estructura que PDF Pág. 3
+    Sortable por columna ahorro (mantener funcionalidad existente)
+
+  Sección Transparencia (condicional):
+    Misma estructura que PDF, banner ámbar
+```
+
+### 4.4 Componentes shadcn a personalizar
+
+Los componentes shadcn que ya existen necesitan tema con los tokens nuevos:
+
+- `Button` variant "default" → fondo `#F59845`, hover `#B45309`
+- `Button` variant "secondary" → border `#E2E8F0`, hover bg `#F8FAFC`
+- `Tabs` → active state con color naranja en lugar de azul
+- `Switch` → naranja cuando checked
+- `Badge` → variantes "automatable" con fondo naranja
+
+---
+
+## 5. Cambios funcionales asociados
+
+### 5.1 Helper `formatPayback`
+
+Crear en `src/lib/format.ts` (o donde ya estén los formatters de moneda).
+
+Tests obligatorios — ver sección 3.4.
+
+Aplicar en:
+- `RoiKpiBar.tsx` (web)
+- `pdf-sections-roi.ts → drawRoiKpiCards`
+- `csv-export.ts` línea de metadata
+
+### 5.2 Detector de ROI inusual ya implementado en Etapa 3
+
+Verificar que la sección Transparencia se renderiza correctamente en el PDF (Sprint 1 Etapa 4 tuvo PDF de 36KB que era anómalo — revisar que ahora con el rediseño tenga densidad razonable).
+
+### 5.3 Overlay badge en BpmnCanvas
+
+El badge ⚡ ya está implementado. Cambios visuales:
+- Fondo de blanco a `#F59845` (más prominente)
+- ⚡ blanco en lugar de ámbar
+- Posición: cambiar de `{ top: -8, right: -8 }` a `{ top: -8, left: elementWidth - 12 }` para no depender del soporte de `right` en bpmn-js v18 (ya identificamos este riesgo en checkpoint anterior)
+
+### 5.4 Carátula del PDF — eliminar
+
+El PDF anterior tenía una carátula con gradient grande. Reemplazar por header denso en página 1 (ver sección 3.2 — Página 1).
+
+---
+
+## 6. Validación E2E
+
+### 6.1 Archivos a generar
+
+Para validar el rediseño, generar los siguientes archivos en `tests/e2e/__output__/`:
+
+**Setup A: medium-with-gateways realista**
+- 3 actividades automatizables (`task_recv`, `task_score`, `task_analisis`)
+- Costos directos: $200/actividad
+- Costos automatizados: $20/actividad
+- Frecuencia anual: 5.000
+- Horizonte: 3 años
+- Inversión: USD 80.000
+
+Generar:
+- `medium-gw_actual_v2.pdf`
+- `medium-gw_automatizado_v2.pdf`
+- `medium-gw_roi_v2.pdf`
+
+**Setup B: medium-with-gateways con ROI inusual**
+- Mismas actividades automatizables
+- Costos automatizados: $1 (para forzar ROI > 1000%)
+- Frecuencia anual: 12.000
+- Inversión: USD 10.000
+
+Generar:
+- `medium-gw_roi_inusual_v2.pdf` — debe mostrar Transparencia Metodológica con aviso de ROI inusual
+
+**Setup C: payback en distintos rangos**
+- `payback_inmediato.pdf` — inversión = 0
+- `payback_corto.pdf` — payback de 0.5 meses
+- `payback_normal.pdf` — payback de 10 meses
+- `payback_largo.pdf` — payback de 30 meses
+
+Generar:
+- `payback_formats.pdf` — uno solo con los 4 casos para verificar el formato visual
+
+### 6.2 Métricas que Claude Code DEBE reportar
+
+Tabla de validación:
+
+```
+┌────────────────────────────┬──────────┬──────────┬───────────────────┐
+│ Archivo                    │ Tamaño   │ Páginas  │ Validación visual │
+├────────────────────────────┼──────────┼──────────┼───────────────────┤
+│ medium-gw_actual_v2.pdf    │ XX KB    │ 3        │ ✓ / ✗            │
+│ medium-gw_automatizado_v2  │ XX KB    │ 3        │ ✓ / ✗            │
+│ medium-gw_roi_v2.pdf       │ XX KB    │ 4        │ ✓ / ✗            │
+│ medium-gw_roi_inusual_v2   │ XX KB    │ 4        │ ✓ / ✗            │
+└────────────────────────────┴──────────┴──────────┴───────────────────┘
+```
+
+**Tamaño esperado por página: 25-50 KB.** Páginas con diagrama BPMN embebido pueden llegar a 60 KB. Si alguna página queda en < 15 KB es señal de que algo no se renderizó.
+
+Análisis de píxeles del heatmap embebido (igual que MVP):
+- Detectar verde, amarillo y rojo en la página del diagrama
+- Verificar que el badge ⚡ naranja `#F59845` está presente (al menos un pixel naranja sobre el diagrama)
+
+Text extraction con pdf-parse para verificar palabras clave:
+- `_actual.pdf`: "Costo total esperado", "Análisis de procesos"
+- `_automatizado.pdf`: "Costo total", "actividades no automatizables"
+- `_roi.pdf`: "Análisis de retorno", "Ahorro anual", "Payback", "ROI"
+- `_roi_inusual.pdf`: TODO lo anterior + "ROI inusualmente alto detectado"
+
+Verificación de marca:
+- En cada PDF, buscar texto exacto "InQ" (con I-n-Q correctos)
+- Verificar que NO aparece "INQ", "Inq", "inq" en ningún PDF
+- Verificar "Powered by InQuality" en cada footer
+
+### 6.3 Validación visual obligatoria por el usuario
+
+Después de generar los archivos, presentarlos vía `present_files` para que el usuario abra los PDFs en Preview y valide:
+
+1. ¿Los KPIs se ven como cards prominentes con el gradiente naranja → magenta?
+2. ¿El diagrama BPMN se ve grande y legible en la página horizontal?
+3. ¿El formato de payback es claro ("10.6 meses" vs "0.0 meses")?
+4. ¿La sección Transparencia metodológica aparece cuando corresponde?
+5. ¿"InQ ROI" y "Powered by InQuality" se ven correctos en headers/footers?
+6. ¿La densidad de información es adecuada (no hay páginas semivacías)?
+
+---
+
+## 7. Definition of Done
+
+- [ ] Manual de marca aplicado: paleta naranja InQ, tipografía consistente, "InQ" siempre I-n-Q
+- [ ] PDF de Comparación + ROI con layout híbrido (vertical + horizontal + vertical + vertical)
+- [ ] PDF de Actual y Automatizado con layout híbrido (vertical + horizontal + vertical)
+- [ ] Página 1 de cada PDF SIN carátula, con header denso que incluye metadata
+- [ ] KPI Hero con gradiente naranja → magenta en PDF y Web
+- [ ] Top 3 ahorros visible en página 1 del PDF ROI
+- [ ] Tabla comparativa con paleta naranja consistente
+- [ ] Footer real al pie de página (no a mitad)
+- [ ] Helper `formatPayback` implementado y aplicado en UI, PDF y CSV
+- [ ] Badge ⚡ en BpmnCanvas con fondo naranja sólido `#F59845`
+- [ ] Posición del badge cambiada a `{ top, left }` (no `right`) — robusto a bpmn-js v18
+- [ ] Web app con identidad: topbar con logo, CTAs naranjas, tabs con color de marca
+- [ ] Panel de Automatización en ActivityPanel con caja naranja destacada
+- [ ] 7 archivos de validación generados en `tests/e2e/__output__/`
+- [ ] Análisis de píxeles confirma badge naranja + heatmap completo
+- [ ] Verificación textual confirma "InQ" correcto en todos los PDFs
+- [ ] `present_files` ejecutado para que el usuario abra los PDFs
+- [ ] 440 tests previos siguen verdes
+- [ ] Nuevos tests de `formatPayback` (≥10 casos)
+- [ ] Build limpio, lint limpio
+- [ ] CHANGELOG.md actualizado con sección "Sprint 1.5 — Rediseño visual"
+- [ ] DESIGN_SYSTEM.md creado con paleta, tipografía y componentes (referencia para Sprint 2+)
+
+---
+
+## 8. Lo que NO entra en Sprint 1.5
+
+- Refinamiento del ícono ⚡ a Bot de Lucide (Sprint 2-3)
+- Nueva entidad `ProcessOverheadCost` para multas/penalidades (Sprint 2-3)
+- Branding completo con logo SVG de InQuality embebido (Sprint 3-4)
+- Excel multi-hoja con identidad (Sprint 3-4)
+- Carátula opcional vía toggle de export (no se necesita por ahora — decidimos no usarla)
+- Animaciones avanzadas en web app (Sprint 4+)
+- Modo oscuro (Sprint 4+)
+
+---
+
+## 9. Cambios en archivos clave
+
+### Nuevos
+- `src/lib/format.ts` (o extender el existente) — `formatPayback`
+- `DESIGN_SYSTEM.md` — referencia visual del sistema
+- `src/lib/export/pdf-sections-shared.ts` — header y footer reutilizables
+- `tests/lib/format-payback.test.ts` — tests del helper
+
+### Modificados
+- `src/lib/export/pdf-export.ts` — soportar orientación landscape en una página
+- `src/lib/export/pdf-sections.ts` — aplicar nuevo manual de marca
+- `src/lib/export/pdf-sections-roi.ts` — rediseño completo del PDF ROI
+- `src/features/workspace/BpmnCanvas.tsx` — badge ⚡ naranja + posición
+- `src/features/workspace/ActivityPanel.tsx` — sección Automatización con caja naranja
+- `src/features/report/RoiKpiBar.tsx` — KPI Hero gradiente + secundarios paleta
+- `src/features/report/ComparisonTable.tsx` — paleta naranja
+- `src/features/report/TransparencySection.tsx` — verificar render correcto
+- `src/components/ui/*` — tokens naranja en components shadcn (button, tabs, switch)
+- `tailwind.config.ts` — extender paleta con tokens InQ
+- `index.css` — definir variables CSS
+
+### En CLAUDE.md, agregar regla crítica
+```
+## Reglas de marca (NO NEGOCIABLES)
+
+1. La versión corta de InQuality SIEMPRE se escribe "InQ":
+   - I mayúscula
+   - n minúscula
+   - Q mayúscula
+   - Cualquier otra forma (INQ, Inq, inq, inQ) es bug
+
+2. El producto se llama "InQ ROI" en este Sprint. Es nombre de trabajo,
+   se reemplazará en Sprint 3-4. No debatir el nombre ahora.
+
+3. Color protagonista: naranja InQ #F59845.
+   Gradiente identidad: #F59845 → #ED3E8F (naranja → magenta).
+   No usar morado de CONCILIA (#572FA2, #CB1889) en este producto.
+
+4. Tagline obligatorio en footers de PDF: "Powered by InQuality".
+
+5. No promover a Marcos como creador del producto. Si aparece nombre del
+   consultor en algún campo, es como "consultor responsable", no como
+   "creador" o "founder".
+```
+
+---
+
+## 10. Orden sugerido de implementación
+
+Para que sea incremental y validable en cada paso:
+
+1. **Setup del sistema de diseño**
+   - Crear `DESIGN_SYSTEM.md`
+   - Extender `tailwind.config.ts` con tokens InQ
+   - Definir variables CSS en `index.css`
+   - Personalizar componentes shadcn (button, tabs, switch)
+
+2. **Helper de formato + tests**
+   - Implementar `formatPayback` con 10 tests
+   - Aplicar en `RoiKpiBar` (web)
+
+3. **Web App: workspace + reporte**
+   - Topbar con logo InQ ROI
+   - ActivityPanel con sección Automatización naranja
+   - Reporte con KPI Hero gradiente y secundarios paleta
+   - Validación visual con usuario
+
+4. **PDF: header y footer compartidos**
+   - Crear `pdf-sections-shared.ts`
+   - Refactorizar PDFs existentes para usar header/footer comunes
+   - Aplicar paleta InQ
+
+5. **PDF: layout híbrido (vertical + horizontal)**
+   - Modificar `pdf-export.ts` para soportar landscape en página específica
+   - Implementar página del diagrama horizontal
+   - Generar primer PDF de validación
+
+6. **PDF: rediseño completo de página 1 ROI**
+   - Header denso sin carátula
+   - KPI Hero, secundarios, top 3, gráfico de trayectoria
+   - Aplicar `formatPayback`
+   - Generar segundo PDF de validación
+
+7. **PDF: páginas 3 y 4 ROI**
+   - Tabla comparativa con paleta
+   - Análisis textual con secciones
+   - Sección Transparencia condicional
+   - Generar tercer PDF de validación
+
+8. **PDFs de Actual y Automatizado**
+   - Aplicar mismo sistema
+   - Verificar consistencia visual
+
+9. **Badge ⚡ en BpmnCanvas**
+   - Color naranja sólido
+   - Posición robusta (top + left)
+   - Test del overlay
+
+10. **Validación E2E final**
+    - Generar los 7 archivos especificados
+    - Análisis de píxeles, text extraction
+    - `present_files` para validación visual del usuario
+
+11. **Documentación**
+    - CHANGELOG.md
+    - Actualizar CLAUDE.md con reglas de marca
+    - Tag de release v0.2.0-sprint1-visual
+
+---
+
+## Notas finales para Claude Code
+
+- Este es un sprint de POLISH, no de features. Si encontrás algo que requiere cambios arquitectónicos importantes (más de 1 hora), PARÁ y consultá con el usuario antes de proceder.
+
+- La validación visual final la hace el usuario abriendo los PDFs en Preview de Mac. Tu trabajo NO es solo generar archivos — es generar archivos QUE SE VEAN COMO EL MOCKUP MUESTRA. No declares la etapa terminada sin haber verificado tamaño, páginas, análisis de píxeles del heatmap, y palabras clave del texto extraído.
+
+- Cada PDF generado pasa por `present_files` para que el usuario lo abra. NO te conformes con "los tests pasaron".
+
+- Si en algún momento de la implementación descubrís que el mockup tiene una inconsistencia o un detalle no especificado, hacé las preguntas explícitamente antes de inventar la respuesta.
+
+- El usuario ha sido riguroso pidiendo validación honesta. Mantené ese estándar: reportá lo que efectivamente verificaste, no lo que asumiste.